A TWI / I2C bootloader for AVR MCUs
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

119 lines
5.6 KiB

6 months ago
6 months ago
6 months ago
6 months ago
  1. # twiboot - a TWI / I2C bootloader for AVR MCUs ##
  2. twiboot is a simple/small bootloader for AVR MCUs written in C. It uses the integrated TWI or USI peripheral of the controller to implement a I2C slave.
  3. It was originally created to update I2C controlled BLMCs (Brushless Motor Controller) without an AVR ISP adapter.
  4. twiboot acts as a slave device on a TWI/I2C bus and allows reading/writing of the internal flash memory.
  5. As a compile time option (EEPROM_SUPPORT) twiboot also allows reading/writing of the whole internal EEPROM memory.
  6. The bootloader is not able to update itself (only application flash memory region accessible).
  7. Currently the following AVR MCUs are supported:
  8. AVR MCU | Flash bytes used (.text + .data) | Bootloader region size
  9. --- | --- | ---
  10. attiny85 | 954 (0x3BA) | 512 words
  11. atmega8 | 786 (0x312) | 512 words
  12. atmega88 | 810 (0x32A) | 512 words
  13. atmega168 | 810 (0x32A) | 512 words
  14. atmega328p | 810 (0x32A) | 512 words
  15. (Compiled on Ubuntu 18.04 LTS (gcc 5.4.0 / avr-libc 2.0.0) with EEPROM and LED support)
  16. ## Operation ##
  17. twiboot is installed in the bootloader section and executed directly after reset (BOOTRST fuse is programmed).
  18. For MCUs without bootloader section see [Virtual bootloader section](#virtual-bootloader-section) below.
  19. While running, twiboot configures the TWI/USI peripheral as slave device and waits for valid protocol messages
  20. directed to its address on the TWI/I2C bus. The slave address is configured during compile time of twiboot.
  21. When receiving no messages for 1000ms after reset, the bootloader exits and executes the main application at address 0x0000.
  22. A TWI/I2C master can use the protocol to
  23. - abort the boot timeout
  24. - query information about the device (bootloader version, AVR signature bytes, flash/eeprom size, flash page size)
  25. - read internal flash / eeprom memory (byte wise)
  26. - write the internal flash (page wise)
  27. - write the internal eeprom (byte wise)
  28. - exit the bootloader and start the application
  29. As a compile time option (LED_SUPPORT) twiboot can output its state with two LEDs.
  30. One LED will flash with a frequency of 20Hz while twiboot is active (including boot wait time).
  31. A second LED will flash when the bootloader is addressed on the TWI/I2C bus.
  32. ### Virtual Bootloader Section ###
  33. For MCUs without bootloader section twiboot will patch the vector table on the fly during flash programming to stay active.
  34. The reset vector is patched to execute twiboot instead of the application code.
  35. Another vector entry will be patched to store the original entry point of the application.
  36. This vector entry is overridden and MUST NOT be used by the application.
  37. twiboot uses this vector to start the application after the initial timeout.
  38. This live patching changes the content of the vector table, which would result in a verification error after programming.
  39. To counter this kind of error, twiboot caches the original vector table entries in RAM and return those on a read command.
  40. The real content of the vector table is only returned after a reset.
  41. ## Build and install twiboot ##
  42. twiboot uses gcc, avr-libc and GNU Make for building, avrdude is used for flashing the MCU.
  43. The build and install procedures are only tested under linux.
  44. The selection of the target MCU and the programming interface can be found in the Makefile,
  45. TWI/I2C slave address and optional components (EEPROM / LED support) are configured
  46. in the main.c source.
  47. To build twiboot for the selected target:
  48. ``` shell
  49. $ make
  50. ```
  51. To install (flash download) twiboot with avrdude on the target:
  52. ``` shell
  53. $ make install
  54. ```
  55. Set AVR fuses with avrdude on the target (internal RC-Osz, enable BOD, enable BOOTRST):
  56. ``` shell
  57. $ make fuses
  58. ```
  59. ## TWI/I2C Protocol ##
  60. A TWI/I2C master can use the following protocol for accessing the bootloader.
  61. Function | TWI/I2C data | Comment
  62. --- | --- | ---
  63. Abort boot timeout | **SLA+W**, 0x00, **STO** |
  64. Show bootloader version | **SLA+W**, 0x01, **SLA+R**, {16 bytes}, **STO** | ASCII, not null terminated
  65. Start application | **SLA+W**, 0x01, 0x80, **STO** |
  66. Read chip info | **SLA+W**, 0x02, 0x00, 0x00, 0x00, **SLA+R**, {8 bytes}, **STO** | 3byte signature, 1byte page size, 2byte flash size, 2byte eeprom size
  67. Read 1+ flash bytes | **SLA+W**, 0x02, 0x01, addrh, addrl, **SLA+R**, {* bytes}, **STO** |
  68. Read 1+ eeprom bytes | **SLA+W**, 0x02, 0x02, addrh, addrl, **SLA+R**, {* bytes}, **STO** |
  69. Write one flash page | **SLA+W**, 0x02, 0x01, addrh, addrl, {* bytes}, **STO** | page size as indicated in chip info
  70. Write 1+ eeprom bytes | **SLA+W**, 0x02, 0x02, addrh, addrl, {* bytes}, **STO** | write 0 < n < page size bytes at once
  71. **SLA+R** means Start Condition, Slave Address, Read Access
  72. **SLA+W** means Start Condition, Slave Address, Write Access
  73. **STO** means Stop Condition
  74. A flash page / eeprom write is only triggered after the Stop Condition.
  75. During the write process twiboot will NOT acknowledge its slave address.
  76. The multiboot_tool repository contains a simple linux application that uses
  77. this protocol to access the bootloader over linux i2c device.
  78. The ispprog programming adapter can also be used as a avr910/butterfly to twiboot protocol bridge.
  79. ## TWI/I2C Clockstretching ##
  80. While a write is in progress twiboot will not respond on the TWI/I2C bus and the
  81. TWI/I2C master needs to retry/poll the slave address until the write has completed.
  82. As a compile time option (USE_CLOCKSTRETCH) the previous behavior of twiboot can be restored:
  83. TWI/I2C Clockstretching is then used to inform the master of the duration of the write.
  84. Please note that there are some TWI/I2C masters that do not support clockstretching.
  85. ## Development ##
  86. Issue reports, feature requests, patches or simply success stories are much appreciated.