From ddb4cd12b2f9fe89dc92674b489c190457e888ed Mon Sep 17 00:00:00 2001 From: Marcel Date: Tue, 4 Mar 2025 20:16:24 +0100 Subject: [PATCH] Made HOWTO a tiny bit better. --- ...firmware-and-compile-it_MeesElectronics.md | 149 +++++++++++++----- 1 file changed, 112 insertions(+), 37 deletions(-) diff --git a/Documentation/HOWTO-change-firmware-and-compile-it_MeesElectronics.md b/Documentation/HOWTO-change-firmware-and-compile-it_MeesElectronics.md index 332ce08..12aec16 100644 --- a/Documentation/HOWTO-change-firmware-and-compile-it_MeesElectronics.md +++ b/Documentation/HOWTO-change-firmware-and-compile-it_MeesElectronics.md @@ -95,9 +95,7 @@ release-waveshare-esp32-s3-pico: 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, 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 +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 the new definition below that line: // Board added by Mees Electronics #define BOARD_WAVESHARE_ESP32_S3_PICO 0x61 // Waveshare ESP32 S3 Pico @@ -110,7 +108,7 @@ Somewhere between these to lines we have to add our board definition. It is good #error An unsupported ESP32 board was selected. Cannot compile RNode firmware. #endif -Like so: +The new code: // Board definition added by Mees Electronics #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO @@ -160,13 +158,15 @@ Like so: } }; - #else - #error An unsupported ESP32 board was selected. Cannot compile RNode firmware. - #endif +A lot of the abilities of the board is defined here. Most of it is self explanatory. In a future update of this document it will be beter explained. For now, the above values should be good enough to get you started. + +The SPI bus is defined in the structs `interfaces`, `interface_cfg` and `interface_pins`. The comments in the code explain it well enough, I think. When the value of `interface_cfg[0]` is set to *false*, we can define all the IO pins in the struct `interface_pins`. The numbers are the GPIO numbers of the ESP32 S3. So 10 means GPIO10. If the value is set to -1 the pin is not used. For example, the SX1278 transceiver doesn't have a busy pin, so it is set to -1. ### Utilities.h -Also, in the file **Utilities.h** add entry. Again, inside the '#if MCU_VARIANT == MCU_ESP32'. +In this file, the routines for the optional external LEDs are defined. If the new board has a NeoPixel, you don't have to change these. But keep reading, because there are some other functions you have to change even if your board has a NeoPixel! + +Search for the line `#if MCU_VARIANT == MCU_ESP32`. Because there are several of these lines, make sure you have the right one: the next line should be `#if HAS_NP == true`. Here you will find a bunch of `#elif BOARD_MODEL ==` lines. Find the last one of this if block, which ends with `#endif`. Add the new section for our board just before the `#endif`: #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO void led_rx_on() { digitalWrite(pin_led_rx, HIGH); } @@ -176,49 +176,117 @@ Also, in the file **Utilities.h** add entry. Again, inside the '#if MCU_VARIANT 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. +Search for the code `bool eeprom_model_valid() {`. This code checks if the BOARD_MODEL, which is stored in the EEPROM corresponds with the running firmware version. If these are not the same, the firmware will not boot. -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: +After adding our new board section, the code looks something like this: - // Added by Mees Electronics +``` +#if BOARD_MODEL == BOARD_RNODE + if (model == MODEL_A4 || model == MODEL_A9 || model == MODEL_FF || model == MODEL_FE) { + #elif BOARD_MODEL == BOARD_RNODE_NG_20 + if (model == MODEL_A3 || model == MODEL_A8) { + #elif BOARD_MODEL == BOARD_RNODE_NG_21 + if (model == MODEL_A2 || model == MODEL_A7) { + #elif BOARD_MODEL == BOARD_T3S3 + if (model == MODEL_A1 || model == MODEL_A6 || model == MODEL_A5 || model == MODEL_AA || model == MODEL_AC) { + #elif BOARD_MODEL == BOARD_HMBRW + if (model == MODEL_FF || model == MODEL_FE) { + #elif BOARD_MODEL == BOARD_TBEAM + if (model == MODEL_E4 || model == MODEL_E9 || model == MODEL_E3 || model == MODEL_E8) { + #elif BOARD_MODEL == BOARD_TDECK + if (model == MODEL_D4 || model == MODEL_D9) { + #elif BOARD_MODEL == BOARD_TECHO + if (model == MODEL_16 || model == MODEL_17) { + #elif BOARD_MODEL == BOARD_TBEAM_S_V1 + if (model == MODEL_DB || model == MODEL_DC) { + #elif BOARD_MODEL == BOARD_LORA32_V1_0 + if (model == MODEL_BA || model == MODEL_BB) { + #elif BOARD_MODEL == BOARD_LORA32_V2_0 + if (model == MODEL_B3 || model == MODEL_B8) { + #elif BOARD_MODEL == BOARD_LORA32_V2_1 + if (model == MODEL_B4 || model == MODEL_B9) { + #elif BOARD_MODEL == BOARD_HELTEC32_V2 + if (model == MODEL_C4 || model == MODEL_C9) { + #elif BOARD_MODEL == BOARD_HELTEC32_V3 + if (model == MODEL_C5 || model == MODEL_CA) { + #elif BOARD_MODEL == BOARD_H_W_PAPER + if (model == MODEL_C8) { + #elif BOARD_MODEL == BOARD_HELTEC_T114 + if (model == MODEL_C6 || model == MODEL_C7) { + #elif BOARD_MODEL == BOARD_RAK4631 + if (model == MODEL_11 || model == MODEL_12 || model == MODEL_13 || model == MODEL_14) { + #elif BOARD_MODEL == BOARD_OPENCOM_XL + if (model == MODEL_21) { + #elif BOARD_MODEL == BOARD_HUZZAH32 + if (model == MODEL_FF) { + #elif BOARD_MODEL == BOARD_HMBRW + if (model == MODEL_FF || model == MODEL_FE) { + #elif BOARD_MODEL == BOARD_GENERIC_ESP32 + if (model == MODEL_FF || model == MODEL_FE) { + // Added by Mees Electronics #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO if (model == MODEL_A4) { + #else +``` -In **Utilities.h** the function **void setTXPower()** defines the LoRa power setting per Lora module/board pair. Add the new board here: +Last, find the line `void setTXPower(RadioInterface* radio, int txp) {`. This is the code that handles the RF power settings of the LoRa transceiver. Here you have to add the proper code for the LoRa module you use. After adding the code for the SX1278 module we use in this example the code should look something like this: - // Added by Mees Electronics - if (model == MODEL_A4) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); +``` +if (model == MODEL_A1) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_A2) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_A3) radio->setTxPower(txp, PA_OUTPUT_RFO_PIN); + if (model == MODEL_A4) radio->setTxPower(txp, PA_OUTPUT_RFO_PIN); + if (model == MODEL_A5) radio->setTxPower(txp, PA_OUTPUT_RFO_PIN); + if (model == MODEL_A6) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_A7) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_A8) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_A9) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_AA) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_AC) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + + if (model == MODEL_B3) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_B4) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_B8) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_B9) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_BA) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_BB) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + + if (model == MODEL_C4) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_C9) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_C5) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_C6) radio->setTxPower(txp, PA_OUTPUT_RFO_PIN); + if (model == MODEL_C7) radio->setTxPower(txp, PA_OUTPUT_RFO_PIN); + if (model == MODEL_CA) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + + if (model == MODEL_D4) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_D9) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + + if (model == MODEL_DB) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_DC) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + + if (model == MODEL_E4) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_E9) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_E3) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_E8) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + + if (model == MODEL_FE) radio->setTxPower(txp, PA_OUTPUT_PA_BOOST_PIN); + if (model == MODEL_FF) radio->setTxPower(txp, PA_OUTPUT_RFO_PIN); + + // 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. +### Display.h - #elif BOARD_MODEL == BOARD_WAVESHARE_ESP32_S3_PICO - disp_mode = DISP_MODE_LANDSCAPE; - display.setRotation(0); +The file **display.h** also has a board specific definition section. If the new board has a display, make sure there is a proper entry for it. Our example board doesn't have a display, so we don't have to change this file. If your board has a display, make sure you make the proper changes. ### 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; +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 only used when the board has a battery installed. Our example board doesn't have a battery, so we don't have to change this file. If your board has a display, make sure you make the proper changes. ### Flashing the board -Make shure you are in the dialout group. If not: +Make sure you are in the dialout group. If not: $ sudo usermod -aG dialout @@ -243,3 +311,10 @@ When the rnode is flashed, it is signed with a key. If you connect the rnode to $ rnodeconf /dev/ttyACM0 --eeprom-wipe $ rnodeconf /dev/ttyACM0 -r --platform ESP32 --model a4 --product f0 --hwrev 3 +# License + +(C) 2025 M.T. Konstapel https://meezenest.nl/mees + +This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. + +Many thanks to Tom for proofreading this document.