Merge pull request #15 from casanovg/v1.5

v1.5

README.md

@@ -1,38 +1,83 @@
-![timonel-bootloader](https://github.com/casanovg/timonel/blob/media/timonel-github-wh.jpg)
+![timonel-bootloader](https://github.com/casanovg/timonel/blob/media/timonel-code.png)
 ## ATtiny85 I2C Bootloader
 
-Timonel is an I2C bootloader for ATtiny85/45/25 microcontrollers. The aim is to enable AVR firmware updates in scenarios where there is a more powerful MCU (ESP8266, Arduino, RPi, BeagleBone, etc.) acting as I2C master and one or more Tiny85 as I2C slave performing peripheral functions.
+Timonel is an I2C bootloader for ATtiny85/45/25 microcontrollers. It is designed to enable AVR firmware updates in scenarios where there is a more powerful MCU (ESP8266, ESP32, Arduino, RPi, BeagleBone, etc.) serving as I2C master and one or more ATtiny85 as I2C slaves that perform peripheral functions.
 
-Some possible cases:
+Some cases:
 
-* A small robot controlled by Raspberry Pi where the specific functions of each limb are delegated to several Tiny85 through an I2C bus.
-* Multi-sensor systems, where each Tiny85 is a node that handles one or more sensors.
+* A small robot controlled by an ESP8266 where each limb specific functions are delegated to several Tiny85 through an I2C bus.
+* Multisensor IoT setups, where each Tiny85 is a node that handles one or more sensors.
 * etc ...
 
-In these situations, it's handy to be able to update the AVRs firmware straight from the I2C master. But, so far (mid-2018), I haven't found an I2C bootloader that fits directly the TinyX5 family, addressing its several limitations:
+In these situations, it is quite convenient to be able to update the AVRs' firmware directly from a single entry point, the I2C master. Depending on the main microcontroller type, the ATtiny updates can even be done wirelessly. However, until now (mid-2018), there doesn't seem to be an I2C bootloader that directly suits the TinyX5 family, addressing its various limitations:
 
-* It doesn't have dedicated hardware to handle I2C, only the USI (Universal Serial Interface).
-* It lacks a protected memory area for the bootloader.
-* It is not possible to redirect the interruption vectors to the bootloader.
+* It does not have dedicated hardware to handle I2C, only the USI (Universal Serial Interface).
+* Lacks a bootloader protected memory area.
+* Unable to redirect interrupt vectors to the bootloader.
 
-That's why I started writing this one.
+That is why this project began ...
 
 ## Usage:
 
 * [Install](/timonel-bootloader/README.md#Installation) "timonel.hex" on a Tiny85 (bare chips or Digisparks).
-* Compile your [application program](/apps) and convert the generated ".hex" into an array of bytes to be included in "timonel-twim-ss" or "timonel-twim-ms" (e.g. uint8\_t payload[size] = { 0xaa, 0xbb, ...}; ). Use "[tml-hexparser](/timonel-hexparser)" for helping to create the array (payload).
-* Use [VS Code](http://code.visualstudio.com) + [PlatformIO](http://platformio.org) to compile and install "[timonel-twim-ss.bin](/timonel-twim-ss)" or "[timonel-twim-ms.bin](/timonel-twim-ms)" (containing the payload) in an arduino-compatible MCU. It has been tested with ESP8266 ESP01 and NodeMCU. **Note:** the ".bin" file provided contains a small payload demo that sends an SOS by blinking PB1.
+* Build your application program as usual, then use "[tml-hexparser](/timonel-hexparser)" to convert the ".hex" file into a byte array "payload.h" to be included in the "data/payloads" folder of "[timonel-mss-esp8266](https://github.com/casanovg/timonel-mss-esp8266)" or "[timonel-mms-esp8266](https://github.com/casanovg/timonel-mms-esp8266)".
+* Use [VS Code](http://code.visualstudio.com) + [PlatformIO](http://platformio.org) to compile and install "[timonel-mss-esp8266](https://github.com/casanovg/timonel-mss-esp8266)" or "[timonel-mms-esp8266](https://github.com/casanovg/timonel-mms-esp8266)" (containing the payload) in an arduino-compatible MCU. It has been tested with ESP8266 ESP01 and NodeMCU. **Note:** The supplied ".bin" file contains a small payload demo that blinks PB1 on the Tiny85.
 * Connect both chips by **I2C** (SDA, SCL and ground).
-* Open an asynchronous terminal (e.g. [MobaXterm](http://mobaxterm.mobatek.net)) connected to the serial port of the I2C master (9600 N 8 1).
-* Run the commands shown on screen for erasing and flashing new firmware on the Tiny85.
+* Open an asynchronous terminal (e.g. [MobaXterm](http://mobaxterm.mobatek.net)) connected to the serial port of the I2C master (115200 N 8 1).
+* Run the "timonel-twim-ss" commands shown on screen for erasing and flashing new firmware on the Tiny85.
 * It is also possible to update the bootloader itself by using "[timonel-updater](/timonel-updater)" (based on the micronucleus upgrade program).
 
+## Repository organization:
+~~~
+timonel                           
+│
+├── timonel-bootloader : Bootloader main folder. It gets built with "avr-gcc" and "make", using the provided scripts.
+│   ├── configs        : Several setups to balance features with memory usage. To be called from the "make-timonel.sh" script.
+│   ├── releases       : Binary files folder, this is where the compiler output is saved.
+│   ├── ...
+│   ├─ make-timonel.sh : Bootloader build script. Use "./make-timonel.sh --help" for usage options and parameters.
+│   └─ flash-timonel-bootloader.sh : Flashing script. It takes a given binary from "releases" and flashes it with "avrdude".
+│
+├── timonel-bootloader-io : Bootloader implemented as a PlatformIO experimental project.
+│   ├── configs           : Several setups to balance features with memory usage. Selected from "platformio.ini".
+│   ├── ...
+│   └─ platformio.ini     : This file controls all the settings and building parameters.
+│
+├── timonel-hexparser   : Utility to convert a ".hex" binary file into a ".h" payload to be included in I2C master apps.
+│   ├── appl-flashable  : Put here application firmware ".hex" files.
+│   ├── appl-payload    : Here are saved the apps, converted to ".h" files by the hexparser.
+│   ├── ...
+│   └─ make-payload.sh  : Hexparser firmware conversion script.
+│
+├── timonel-updater       : Utility to convert a Timonel binary into a bootloader ".h" update payload for am I2C master.
+│   ├── tmlupd-flashable  : Put here Timonel bootloader ".hex" binary files.
+│   ├── tmlupd-flashable  : Here are saved the ".h" Timonel payloads for updating the bootloader.
+│   ├── ...
+│   └─ make-updater.sh    : Timonel bootloader updater conversion script.
+~~~
+
+## Dependence on other repositories:
+
+#### Libraries
+
+* **[Nb_Micro](https://github.com/casanovg/Nb_Micro)**: Arduino library to control devices that implement the NB command set over an I2C bus.
+* **[Nb_TimonelTwiM](https://github.com/casanovg/Nb_TimonelTwiM)**: Arduino library for uploading firmware to a microcontroller running the Timonel bootloader. It uses the NbMicro library to access the I2C bus.
+* **[Nb_TwiBus](https://github.com/casanovg/Nb_TwiBus)**: Arduino library to scan the I2C bus in search of connected devices addresses and data. It uses the TimonelTwiM library bootloader object definition.
+* **[nb-twi-cmd](https://github.com/casanovg/nb-twi-cmd)**: NB TWI (I2C) command set.
+
+#### Demo I2C master test applications
+
+* **[timonel-mss-esp8266](https://github.com/casanovg/timonel-mss-esp8266)**: Timonel I2C master **single slave**. Serial console-based application that allows sending commands to a device that runs the bootloader from an ESP8266.
+* **[timonel-mms-esp8266](https://github.com/casanovg/timonel-mms-esp8266)**: Timonel I2C master **multi slave**. Serial console-based application that runs a loop that flashes, deletes and runs a user application on several Tiny85's running the bootloader from an ESP8266.
+
 ## Contributing:
 
 Contributions are welcome! If you want to add a new feature, please feel free to create a pull request or open an issue :o)
 
 ## Version History:
 
+**v1.5** \- 2020\-07\-03: Functional Release: Optional commands READEEPR and WRITEEPR have been added to read and write data to the EEPROM as well as the READDEVS command that allows reading the device signature, fuses, and lock bits. A few code fixes and a "pre-main" startup file reduction allows getting an additional flash memory page for applications. The overall project repository was restructured, now the I2C libraries and examples are held on separate git repositories to handle the versioning independently. Added an experimental [PlatformIO project](/timonel-bootloader-io) folder to handle the bootloader building in a more structured way. However, for the moment, the [Make version](/timonel-bootloader) is still the recommended one.
+
 **v1.4** \- 2019\-10\-29: Functional Release: Significant memory saving by inlining the TWI driver functions\, now the smaller version "tml\-t85\-small" occupies less than 1 kB\, leaving 7 kB available for user applications\. Speed improvement through a code tuning to transmit 32\-byte packets \(half a page of memory in a Tiny85\)\. User\-application "**autorun**" is now optional. Internal clock configuration support improved. [Interactive master](/timonel-twim-ss) test program improved with streamlined libs (see it [working](http://youtu.be/-7GOMToGvzI)). [Multi-slave master](/timonel-twim-ms) test program added (see it [working](http://youtu.be/PM9X1thrdOY)).
 
 **v1.3** \- 2019\-06\-06: Functional Release: Bootloader inline functions \(smaller code\) and low fuse auto clock tweaking\. Support for 1\, 2\, 8 and 16 MHz clock speed in user\-application mode\. TWI master UploadApplication refactoring\, now supports both types of page address calculation and both modes of **APP\_USE\_TPL\_PG**. Several bug fixes.
@@ -49,8 +94,6 @@ Contributions are welcome! If you want to add a new feature, please feel free to
 
 **v0.7** \- 2018\-09\-07: Non\-functional\.
 
-**v0.4** \- 2018\-08\-10: Non\-functional\.
-
 ## Credits:
 
 I would like to thank the guys @ [AVRFreaks.net](http://www.avrfreaks.net), specially joeymorin and clawson) for sharing their vast knowledge and technical advice in general. Many thanks also to Donald Papp @ Hackaday for [posting about this](https://hackaday.com/2018/10/20/i2c-bootloader-for-attiny85-lets-other-micros-push-firmware-updates).

timonel-bootloader-io/README.md

@@ -1,37 +1,32 @@
-# Timonel Bootloader v1.5
+# Timonel Bootloader v1.5 - PlatformIO experimental project
 
-Changes from previous version:
+This folder contains the same bootloader version and functionality as the "[Make version](/timonel-bootloader)", but it was implemented as a [PlatformIO](http://platformio.org) experimental project to handle building in a more structured way. Some advantages of using this platform are:
 
-* **Slightly smaller bootloader footprint:** some memory got by removing unused pre-checks from the "crt1.S" initialization file (before calling main), and tweaking compiler options. Now smallest bootloader size, when compiled using the "tml-t85-small" @8Mhz configuration, is ~880 bytes (less than 14 pages). This leaves **7.3 Kbytes (114 pages) available for the user application** on an ATtiny85.
-* **READDEVS command added:** this optional command allows getting the device signature bytes, lock, and fuse bits from the device.
-* **READEEPR and WRITEEPR commands added:** These optional commands are to read and write data to the device's EEPROM. The extended features flag 5 "EEPROM_ACCESS" includes/excludes both commands from the bootloader binary.
+* Development standardization of all components on a single platform: bootloader master and slave sides, I2C libraries, applications, etc. This is possible even with different frameworks: ESP8266, AVR, Arduino, etc.
+* One-click compilation, handled by structured ".ini" and "JSON" files.
+* Simple and orderly updating of platforms and libraries, with a centralized registry of library versions.
+* GitHub integration, Editor IntelliSense (VS Code).
 
-## Compilation
+It is possible that in the future this version will supersede the "Make version", but so far (July 2020), several issues have to be solved:
 
-The **"make-timonel.sh"** script allows launching "[make](http://www.gnu.org/software/make)" with different configurations. It has several arguments, including **"--all"**, which compiles all the preconfigured options found in the **"configs"** directory. The flashable **".hex"** binary files are saved in the **"releases"** directory.
+* The handling of the various bootloader settings in ".ini" files works, but is not yet polished enough.
+* To resolve the previous point, custom variables have been added in the ".ini" files that are unknown by PlatformiIO, throwing warnings at the time of compilation.
+* The size of the binary files obtained in all configurations is substantially larger than their counterparts built with Make.
+* The way to correctly control the platform default compiler version has not been found yet, nor the options that Platformio passes to the compiler and the linker.
 
-E.g: <b>`./make-timonel.sh tml-t85-small timonel 13 1B80 1 false;`</b>
+## Compilation
 
-* Generates a **"timonel.hex"** binary file based on **"tml-t85-small"** config.
-* Assigns the TWI address **13** to the device in bootloader mode.
-* Sets **0x1B80** as the bootloader start memory position.
-* Sets the device low fuse to operate at **1 MHz** in user-application mode.
-* **Disables** automatic clock tweaking.
+It is possible to compile all the bootloader configurations with a single click using the **"Build"** option of the PlatformIO project tasks, from the icon located in the editor footer or the "platform run" command.
 
-**Note:** This bootloader version has been compiled with the **"avr-gcc 8.3.0 64-bit"** toolchain downloaded from [this site](http://blog.zakkemble.net/avr-gcc-builds)., it's also included under the "[avr-toolchains](http://github.com/casanovg/avr-toolchains)" repository. The scripts are included mainly to ease to repetitive work of flashing several devices but, of course, the bootloader can be compiled and flashed using avr-gcc and avrdude directly.
+The bootloader configurations to be built are controlled by lines added under the "extra_configs" section of the "platformio" option in the platformio.ini file. Each line includes a ".ini" file from the "configs" folder with the specific environment configuration parameters.
 
-## <a id="Installation"></a>Flashing Timonel on the device
+To build a single configuration (or just a few), it can be added in the "default_envs" section.
 
-The **"flash-timonel-bootloader.sh"** script allows flashing Timonel on the device by using the "[avrdude](http://savannah.nongnu.org/projects/avrdude)" utility with an [AVR programmer](http://www.fischl.de/usbasp). The supported arguments are:
-
-1. Binary file name (without ".hex" extension), located under "releases" directory.
-2. Clock speed in MHz: 16, 8, 2, 1.
-The bootloader can be flashed to bare ATtiny85/45/25 chips, Digispark boards and other Tiny85-compatible devices using an AVR programmer (e.g. USBasp).
+## <a id="Installation"></a>Flashing Timonel on the device
 
-E.g: <b>`./flash-timonel-bootloader.sh timonel 1;`</b>
+To update the bootloader on the device, use the **"PlatformIO Upload"** command found in project tasks, in the editor footer, or through "platformio run" in the command line.
 
-* Flashes **"timonel.hex"** binary file on the device with avrdude.
-* Sets the device's low fuse to run at **1 MHz** (possible values are 1, 2, 8 and 16).
+E.g. **"platformio.exe run -e tml-t85-std --target upload"** will build and flash the Timonel standard configuration into the device using the programmer configured in platformio.ini (default: [USBasp](http://www.fischl.de/usbasp)).
 
 ## Setting optional features
 
@@ -50,3 +45,5 @@ The bootloader has several optional features that allow finding the right balanc
 * **FORCE\_ERASE\_PG**: If this option is enabled, each flash memory page is erased before writing new data. Normally, it shouldn't be necessary to enable it. (Default: false).
 * **CLEAR\_BIT\_7\_R31**: This is to avoid that the first bootloader instruction is skipped after restarting without an user application in memory. See: http://www.avrfreaks.net/comment/2561866#comment-2561866. (Default: false).
 * **CHECK\_PAGE\_IX**: If this option is enabled, the page index size is checked to ensure that isn't bigger than SPM\_PAGESIZE (64 bytes in an ATtiny85). This keeps the app data integrity in case the master sends wrong page sizes. (Default: false).
+* **CMD\_READDEVS**: This option enables the READDEVS command. It allows reading all fuse bits, lock bits, and device signature imprint table. (Default: false).
+* **EEPROM_ACCESS**: This option enables the READEEPR and WRITEEPR commands, which allow reading and writing the device EEPROM. (Default: false).

timonel-bootloader-io/configs/tml-t85-full-auto.ini

@@ -9,15 +9,21 @@
 # Configuration:   Full Auto: Auto CLK + All features enabled, except APP_USE_TPL_PG
 
 [env:tml-t85-full-auto]
-twi_addr = 11                   ; Bootloader TWI (I2C) address
+; NOTE: These custom settings are unknown to PlatformIO, so warning messages
+; are generated at build time. However, since they define fundamental bootloader
+; parameters, they'll be kept here visible until a better solution is found,
+; avoiding defining them in external scripts.
+;twi_addr = 11                  ; Bootloader TWI (I2C) address
 timonel_start = 0x18C0          ; Bootloader start memry location
-target = "timonel"              ; Map file name
+;target = "timonel"             ; Map file name
+
+; Bootloader build flags
 build_flags =
-; Bootloader TWI (I2C) address
+    ; Bootloader TWI (I2C) address
     -D TWI_ADDR=${env:tml-t85-full-auto.twi_addr}
-; Bootloader start memory position
+    ; Bootloader start memory position
     -D TIMONEL_START=${env:tml-t85-full-auto.timonel_start}
-; Bootloader optional features
+    ; Bootloader optional features
     -D ENABLE_LED_UI=true
     -D AUTO_PAGE_ADDR=true
     -D APP_USE_TPL_PG=false
@@ -28,16 +34,13 @@ build_flags =
     -D CMD_READFLASH=true
     -D CMD_READDEVS=true
     -D EEPROM_ACCESS=true
+    ; Warning: Please modify the below options with caution ...
     -D AUTO_CLK_TWEAK=true
-    -D LOW_FUSE=0x62
+    -D LOW_FUSE=0x62            ; 1 Mhz application clock setting
     -D LED_UI_PIN=PB1
-; Project name (Binary ".hex" file name)
+    ; Project name (Binary ".hex" file name)
     -D PROJECT_NAME=tml-t85-full-auto
-; Optimization options
-    -Wall -g2 -Os -std=gnu99
-    -ffunction-sections -fdata-sections
-    -nostartfiles
-    -funsigned-char -funsigned-bitfields -fpack-struct -fshort-enums -mno-interrupts -mtiny-stack
-    -fno-inline-small-functions -fno-move-loop-invariants -fno-tree-scev-cprop -fno-jump-tables    
-; Linker options
-    -Wl,--relax,--section-start=.text=${env:tml-t85-full-auto.timonel_start},--gc-sections,-Map=${env:tml-t85-full-auto.target}.map
+    ; Common build flags
+    ${env.build_flags}
+    ; Linker options
+    -Wl,--relax,--section-start=.text=${env:tml-t85-full-auto.timonel_start},--gc-sections  ;,-Map=${env:tml-t85-full-auto.target}.map