# How to compile the rnode firmware yourself

## Required knowledge

This document assumes some basic knowledge of programming. Like using code editors to edit source code and using basic commands like `make`. Plus some basic Linux knowledge.

## Dependencies

Make sure *git*, *make*, *python* and *pip* are installed. Most likely these are already available on your system. Otherwise do:

    $ sudo apt install git
    $ sudo apt install make
    $ sudo apt install pip
    $ sudo apt install python

Install Reticulum:

    $ pip install rns --break-system-packages

Add new directories to path:

    $ nano ~/.bashrc

Add `export PATH=~/.local/bin:~/bin:$PATH` to the end of the file. Exit with `CTRL-x` and type `y` to save the changes.

Now reload the shell so the changes to the path will take effect: `exec $SHELL`. You can also logout and login again.

Download arduino-cli:

    $ cd
    $ curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

## Clone git repo

    $ cd
    $ git clone https://github.com/liberatedsystems/RNode_Firmware_CE.git

## Prepare

Install the required BSP and libraries for the ESP32 system.

    $ cd RNode_Firmware_CE/
    $ make prep-esp32

Sometimes this command stalls. If this happens, stop the command by hiting `CTRL-c` and restarted it.

## Test

To test if you can compile the firmware try it:

    $ make firmware-heltec32_v3

Be patient, this can take up to 15 minutes to complete. Wait for the command prompt to return. You should not see any errors.

## Define a new board

Go to the directory `~/RNode_Firmware_CE`. This is the source code of the RNode firmware. Here you will find all the files needed to compile the firmware. You can edit these files with any text editor you like.

Let's say we want to add support for the Waveshare ESP32-S3 Pico with an SX1278 LoRa transceiver. First we have to define a BOARD_MODEL. This is an 8 bit value that is used in the source code to select the right code for the hardware. Let's choose  0x61 as the BOARD_MODEL as this number is not used yet. Optional we can also define a BOARD_VARIANT. This defines the variant of the board. A board could come with different LoRa transceivers, for example. It is also a unique 8 bit number. For now, we ignore this BOARD_VARIANT and only use the BOARD_MODEL.

### Makefile

The source code is compiled using `make` and the file called *Makefile*.

Every target board has a section `firmware-<board_name>`, `upload-<board-name>` and `release-<board-name>`. In the Makefile, three new sections for our new board have to be added. The exact place is not critical. But it is good practice to put them alongside the already present sections for firmware, upload and release.

```
# Added board from Mees Electronics
firmware-waveshare-esp32-s3-pico:
	    arduino-cli compile --fqbn "esp32:esp32:esp32s3:CDCOnBoot=cdc" $(COMMON_BUILD_FLAGS) --build-property "compiler.cpp.extra_flags=\"-DBOARD_MODEL=0x61\""
```

```
# Added board from Mees Electronics
upload-waveshare-esp32-s3-pico:
    arduino-cli upload -p $(or $(port), /dev/ttyACM0) --fqbn esp32:esp32:esp32s3
    @sleep 1
    rnodeconf $(or $(port), /dev/ttyACM0) --firmware-hash $$(./partition_hashes ./build/esp32.esp32.esp32s3/RNode_Firmware_CE.ino.bin)
    @sleep 3
    python3 ./Release/esptool/esptool.py --port $(or $(port), /dev/ttyACM0) --chip esp32-s3 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size 4MB 0x210000 ./Release/console_image.bin
```

```
release-waveshare-esp32-s3-pico:
    arduino-cli compile --fqbn "esp32:esp32:esp32s3:CDCOnBoot=cdc" $(COMMON_BUILD_FLAGS) --build-property "compiler.cpp.extra_flags=\"-DBOARD_MODEL=0x61\""
    cp ~/.arduino15/packages/esp32/hardware/esp32/$(ARDUINO_ESP_CORE_VER)/tools/partitions/boot_app0.bin build/rnode_firmware_waveshare-esp32-s3-pico.boot_app0
    cp build/esp32.esp32.waveshare-esp32-s3-pico/RNode_Firmware_CE.ino.bin build/rnode_firmware_waveshare-esp32-s3-pico.bin
    cp build/esp32.esp32.waveshare-esp32-s3-pico/RNode_Firmware_CE.ino.bootloader.bin build/rnode_firmware_waveshare-esp32-s3-pico.bootloader
    cp build/esp32.esp32.waveshare-esp32-s3-pico/RNode_Firmware_CE.ino.partitions.bin build/rnode_firmware_waveshare-esp32-s3-pico.partitions
    zip --junk-paths ./Release/rnode_firmware_waveshare-esp32-s3-pico.zip ./Release/esptool/esptool.py ./Release/console_image.bin build/rnode_firmware_waveshare-esp32-s3-pico.boot_app0 build/rnode_firmware_waveshare-esp32-s3-pico.bin build/rnode_firmware_waveshare-esp32-s3-pico.bootloader build/rnode_firmware_waveshare-esp32-s3-pico.partitions
    rm -r build
```

### Boards.h

The file `Board.h` is the most important file to edit. This is the place where the supported boards are defined. For our new board should, a new section has to be added. This section defines the pinout of the SPI port and if it has certain peripherals such as a screen or BLE.

First, the new board has to be defined at the beginning of the file. Search for the line `#define MODEL_FF  0xFF // Homebrew board, max 14dBm output power` and add our definition below that line. Like so:

    #define MODEL_FF            0xFF // Homebrew board, max 14dBm output power

    // Board added by Mees Electronics
    #define BOARD_WAVESHARE_ESP32_S3_PICO 0x61 // Waveshare ESP32 S3 Pico

Next, search for the line `#if MCU_VARIANT == MCU_ESP32`. This is the part where all the ESP32 variant are defined. This section stops at the line `#elif MCU_VARIANT == MCU_NRF52`. From here the definitions for the NRF52 board begin.

Somewhere between these to lines we have to add our board definition. It is good practice to add it at the end, just before the following code:

    #else
      #error An unsupported ESP32 board was selected. Cannot compile RNode firmware.
    #endif

Like so:

    // Board definition added by Mees Electronics
    #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO
      #define IS_ESP32S3 true
      #define HAS_DISPLAY false
      #define HAS_BLUETOOTH false
      #define HAS_BLE true
      #define HAS_PMU true
      #define HAS_CONSOLE true
      #define HAS_EEPROM true
      #define INTERFACE_COUNT 1

      #define HAS_NP true
      const int pin_np = 21;
      #if HAS_NP == false
        #if defined(EXTERNAL_LEDS)
          const int pin_led_rx = 16;
          const int pin_led_tx = 17;
        #else
          const int pin_led_rx = 21;
          const int pin_led_tx = 21;
        #endif
      #endif

      const uint8_t interfaces[INTERFACE_COUNT] = {SX1278};
      const bool interface_cfg[INTERFACE_COUNT][3] = {
                    // SX1278
          {
              false, // DEFAULT_SPI
              false, // HAS_TCXO
              false  // DIO2_AS_RF_SWITCH
          },
      };
      const int8_t interface_pins[INTERFACE_COUNT][10] = {
                  // SX1278
          {
               10, // pin_ss
               12, // pin_sclk
               11, // pin_mosi
               13, // pin_miso
               -1, // pin_busy
               15, // pin_dio
               14, // pin_reset
               -1, // pin_txen
               -1, // pin_rxen
               -1  // pin_tcxo_enable
          }
      };

    #else
      #error An unsupported ESP32 board was selected. Cannot compile RNode firmware.
    #endif

### Utilities.h

Also, in the file **Utilities.h** add entry. Again, inside the '#if MCU_VARIANT == MCU_ESP32'.

    	#elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO
            void led_rx_on()  { digitalWrite(pin_led_rx, HIGH); }
            void led_rx_off() {	digitalWrite(pin_led_rx, LOW); }
            void led_tx_on()  { digitalWrite(pin_led_tx, HIGH); }
            void led_tx_off() { digitalWrite(pin_led_tx, LOW); }
            void led_id_on()  { }
            void led_id_off() { }

In **Utilities.h** the functions **led_indicate_info()**, **led_indicate_standby()** and **led_indicate_not_ready()** is also defined for the different boards. If the new board has a NeoPixel, nothing has to be added her.

In **Utilities.h** the function **bool eeprom_model_valid()** also has some board specific definitions. Make sure these are set correctly to prevent an EEPROM error during startup:

    // Added by Mees Electronics
	#elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO
	if (model == MODEL_A4) {

In **Utilities.h** the function **void setTXPower()** defines the LoRa power setting per Lora module/board pair. Add the new board here:

	// Added by Mees Electronics
	if (model == MODEL_A4) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN);

The file **display.h** also has a board definition section. If the new board has a display, make sure there is a proper entry for it.  Again, inside the '#if MCU_VARIANT == MCU_ESP32'. If the board does not have a display, don't define this section.

    #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO
        disp_mode = DISP_MODE_LANDSCAPE;
        display.setRotation(0);

### Power.h

The file **Power.h** must also have a board definition. And also proper definitions in **void measure_battery()** and **bool init_pmu()**. These are more elaborate and not yet fully understood, but probably used when the board has a battery installed. If the new board does not have a battery, do not define anything here!

    #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO
        #define BAT_V_MIN       3.15
        #define BAT_V_MAX       4.3
        #define BAT_V_CHG       4.48
        #define BAT_V_FLOAT     4.33
        #define BAT_SAMPLES     5
        const uint8_t pin_vbat = 35;
        float bat_p_samples[BAT_SAMPLES];
        float bat_v_samples[BAT_SAMPLES];
        uint8_t bat_samples_count = 0;
        int bat_discharging_samples = 0;
        int bat_charging_samples = 0;
        int bat_charged_samples = 0;
        bool bat_voltage_dropping = false;
        float bat_delay_v = 0;
        float bat_state_change_v = 0;

### Flashing the board

Make shure you are in the dialout group. If not:

    $ sudo usermod -aG dialout <username>

If you are flashing a custom board, you will need to generate a signing key in rnodeconf prior to flashing if you do not already have one by running:

    $ rnodeconf -k

Than flash the firmware.

    $ make upload-waveshare-esp32-s3-pico

This will end with error 'This device has not been provisioned yet, cannot set firmware hash'. But fear not. After flashing a custom board, you will also need to provision the EEPROM before use:

    $ rnodeconf /dev/ttyACM0 -r --platform ESP32 --model a4 --product f0 --hwrev 3

Sometimes the board give error whule flashing. Try flashing the board via the other serial interface (ttyACM1). Don't know why, but it works.

### Migrating to a other system

When the rnode is flashed, it is signed with a key. If you connect the rnode to another system, this key cannot be validated. It is possible to write a new key to the rnode by erasing the eeprom and writing the local key to it.

    $ rnodeconf /dev/ttyACM0 --eeprom-wipe
    $ rnodeconf /dev/ttyACM0 -r --platform ESP32 --model a4 --product f0 --hwrev 3