casanovg / timonel

ATtiny85/45/25 I2C bootloader

ATtiny85 I2C Bootloader

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 cases:

• 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 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 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 is why this project began ...

Usage:

• Install "timonel.hex" on a Tiny85 (bare chips or Digisparks).
• Build your application program as usual, then use "tml-hexparser" to convert the ".hex" file into a byte array "payload.h" to be included in the "data/payloads" folder of "timonel-mss-esp8266" or "timonel-mms-esp8266".
• Use VS Code + PlatformIO to compile and install "timonel-mss-esp8266" or "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) 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" (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: Arduino library to control devices that implement the NB command set over an I2C bus.
• 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: 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: NB TWI (I2C) command set.

Demo I2C master test applications

• 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: 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.
• timonel-ota-demo: This demo application shows a series of steps performed by an ESP8266 I2C master to check a website for updates, retrieve a new firmware file from the internet, and update an ATtiny85 slave microcontroller over the I2C bus.

Contributing:

Contributions are welcome! If you want to add a new feature, please feel free to create a pull request, open an issue, or start a discussion :o)

Version History:

v1.6 - 2020-09-25: Functional Release: Supported devices range extended to all AVR microprocessors with Universal Serial Interface (USI). However, at release time, it's only thoroughly tested on the ATtinyX5 and ATtinyX4 series.

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 folder to handle the bootloader building in a more structured way. However, for the moment, the Make version 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 test program improved with streamlined libs (see it working). Multi-slave master test program added (see it working).

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.

v1.2 - 2019-05-15: Functional Release: "Good-neighbor" behavior fixes data dump operation interferences among Timonel devices in multi-device bus setups. The TWI master functionality has been packed in a couple of Arduino libraries to ease the handling of the several configuration options. Timonel-master-ss firmware shows its usage. The TWI master code was moved to PlatformIO.

v1.1 - 2018-10-29: Functional Release: Optional ReadFlash command added. Minor tweaks for running Timonel @ 8 MHz.

v1.0 - 2018-10-05: Functional Release: Optional features implemented.

v0.9 - 2018-09-29: Functional pre-release: Temporary page buffer and other minor issues solved.

v0.8 - 2018-09-16: First functional pre-release.

v0.7 - 2018-09-07: Non-functional.

Credits:

I would like to thank the guys @ 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.

timonel's Issues

error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode

Should i add -std=c99?

root@bananapim2zero:~/timonel/timonel-bootloader# make
tml-bootloader.c: In function ‘main’:
tml-bootloader.c:200:25: error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode
for (int i = 0; i < PAGE_SIZE - 2; i += 2) {
^
tml-bootloader.c:200:25: note: use option -std=c99, -std=gnu99, -std=c11 or -std=gnu11 to compile your code
tml-bootloader.c: In function ‘ReceiveEvent’:
tml-bootloader.c:247:5: error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode
for (byte i = 0; i < commandBytes; i++) {
^
tml-bootloader.c: In function ‘RequestEvent’:
tml-bootloader.c:293:13: error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode
for (byte i = 0; i < GETTMNLV_RPLYLN; i++) {
^
tml-bootloader.c:347:17: error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode
for (byte i = 3; i < (RXDATASIZE + 1); i += 2) {
^
tml-bootloader.c:354:17: error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode
for (byte i = 1; i < (RXDATASIZE + 1); i += 2) {
^
tml-bootloader.c:364:13: error: ‘for’ loop initial declarations are only allowed in C99 or C11 mode
for (byte i = 0; i < WRITPAGE_RPLYLN; i++) {
^
Makefile:55: recipe for target 'tml-bootloader.o' failed
make: *** [tml-bootloader.o] Error 1

sketch for attiny85 firmware upload by air.

Please write a sketch for attiny85 firmware upload by air.
There are many sketches of flashing esp8266 itself on wifi. .
Task: esp8266 get the firmware via wifi and upload it to your slave ittiny85 via i2c.

Thanks in advance.

Feature request for bootloader (if it possible)

Dear Gustavo,

It is a very good feature, thank you! I have a new feature request:

I will make more than one attiny85 module (but i don't know how many pieces, about 3-4 variety but summary about 30 attiny85 module per board), but i don't want a make fix i2c slave address for the bootloader. So, my question: is it possible that the bootloader check the free i2c slave address, and if got it a free address reserve it? (the currently range is ok)

Summary:

• attiny85 power on
• Started the bootloader
• Bootloader firstly runs an "i2cdetect" and search an free i2c address
• if found it then reserved it, and then more works as i2c slave.
• and the currently processing running.

Thank You,
Gabor

syntax error in bash script

In flash-timonel-bootloader.sh running under Linux (it's a 64-bit Ubuntu derivative) the line following
echo "[[[ Flashing Timonel for operating @ $ARG2 MHz ]]]";
is

avrdude -c USBasp -p attiny85 -B3 -U flash:w:.\releases\$ARG1.hex:i -B 20 -U lfuse:w:$LOW_FUSE:m -U hfuse:w:$HIGH_FUSE:m -U efuse:w:$EXTENDED_FUSE:m;

This breaks my bash script. I assume you mean to use / rather than \ here?
avrdude -c USBasp -p attiny85 -B3 -U flash:w:./releases/$ARG1.hex:i -B 20 -U lfuse:w:$LOW_FUSE:m -U hfuse:w:$HIGH_FUSE:m -U efuse:w:$EXTENDED_FUSE:m;

The backslash makes me wonder that perhaps you use Windows with a bash emulation of some kind which allows \ as a path separator, but "real" Linux file systems are more fussy. I make the change and the script runs to completion without errors.

Bash version
GNU bash, version 4.4.20(1)-release (x86_64-pc-linux-gnu)

uname -a reports
Linux robert-ThinkPad-S3-Yoga-14 5.4.0-72-generic #80~18.04.1-Ubuntu SMP Mon Apr 12 23:26:25 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

make-timonel.sh under Linux

"make-timonel-sh" doesn't execute under Linux (more properly when I use it from bash shell)

./make-timonel.sh: 40: ./make-timonel.sh: function: not found
(then the "Usage text"
./make-timonel.sh: 79: ./make-timonel.sh: Syntax error: "}" unexpected

Problem seems to be line 1 hash-bang

#!/bin/sh

If I change this #!/bin/bash, it works

I suspect that your development environment regards bash and sh as functionally equivalent. but for me sh and bash are different executables. Lordy, lordy, I love Unix but how many shells can one operating system need? The documentation says that sh is synonym for dash, but that bash is different. Presumably my sh (dash) doesn't like your function syntax.... argggh. Workaround for me is to edit line 1. as noted above. I'm not really sure what linux best practice is here, and if there some incantation which always picks the right shell? I didn't want to submit a PR not knowing best practice.

As a sanity check, the sample output for ./make-timonel.sh tml-t85-small timonel 13 1B80 1 false is attached below.

---

• Starting Timonel compilation with these parameters:

• ---

• Configuration: tml-t85-small

•  Binary file: timonel.hex
  

•  TWI address: 13
  

• Flash position: 1B80 <- In case of errors, use lower positions!
• CPU clock speed: 1 MHz <- RC OSC (low fuse = 0x62)
• Auto clock tweak: false

---

RUNNING: make all CONFIG=tml-t85-small TARGET=timonel TIMONEL_TWI_ADDR=13 TIMONEL_START=1B80 LOW_FUSE=0x62 AUTO_CLK_TWEAK=false

========================================================================

Building Timonel configuration: tml-t85-small
TIMONEL_START = 0x1B80
========================================================================
... ENABLE_LED_UI = false
... AUTO_PAGE_ADDR = false
... APP_USE_TPL_PG = false
... CMD_SETPGADDR = true
... TWO_STEP_INIT = false
... USE_WDT_RESET = false
... APP_AUTORUN = false
... CMD_READFLASH = false
... CMD_READDEVS = false
... EEPROM_ACCESS = false
-----------------------------------------------------------------------
... AUTO_CLK_TWEAK = false
... LOW_FUSE = 0x62
... LED_UI_PIN = PB1

---

[Sections]
text data bss dec hex filename
896 0 198 1094 446 timonel.bin

[Hexfile] Take "data" size to calculate the bootloader's start address!
text data bss dec hex filename
0 896 0 896 380 timonel.hex

Timonel on TinyX4

Can this bootloader be fitted to work with the ATTinyX4 family?