Added firmware flashing scripts and instructions

Author: ZodiusInfuser

firmware/firmware_update.py

@@ -0,0 +1,238 @@
+
+# To make the Pi not drop I2C clockspeed to 250kHz from 400kHz, one can say:
+# echo "performance" > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
+
+# Usage: python firmware_update.py filename.hex
+
+import binascii
+
+import sys
+import time
+
+
+from smbus2 import SMBus, i2c_msg
+
+
+# Small nuvoton:
+bootloader_id       = 0xB001
+bootloader_version  = 172
+bootloader_i2c_addr = 0x6F
+flash_size          = 16384-2048
+
+I2C_WRITE_MAX_SIZE  = 32
+
+REG_APROM_FLASH    = 0x10
+REG_FLASH_PAGE     = 0xF0
+REG_CHIP_ID_L      = 0xfa
+REG_CHIP_ID_H      = 0xfb
+REG_VERSION        = 0xfc
+REG_DEBUG          = 0xF8
+REG_BOOTLOADER_CMD = 0xF3
+
+REG_CTRL           = 0xfe
+MASK_CTRL_FREAD    = 0x4
+MASK_CTRL_FWRITE   = 0x8
+
+PAGE_SIZE          = 128
+
+i2c_dev = SMBus(1)
+
+def i2c_write_bytes(address, start_reg, valuelist):
+    assert( len(valuelist) <= I2C_WRITE_MAX_SIZE )
+    msg_w = i2c_msg.write(address, [start_reg] + valuelist)
+    i2c_dev.i2c_rdwr(msg_w)
+
+
+def i2c_read_bytes(address, start_reg, length):
+    assert( length <= I2C_WRITE_MAX_SIZE )
+    msg_w = i2c_msg.write(address, [start_reg])
+    i2c_dev.i2c_rdwr(msg_w)
+    msg_r = i2c_msg.read(address, length)
+    i2c_dev.i2c_rdwr(msg_r)
+    return list(msg_r)
+
+
+def i2c_read8(address, reg):
+    """Read a single (8bit) register from the device."""
+    msg_w = i2c_msg.write(address, [reg])
+    i2c_dev.i2c_rdwr(msg_w)
+    msg_r = i2c_msg.read(address, 1)
+    i2c_dev.i2c_rdwr(msg_r)
+    return list(msg_r)[0]
+
+def i2c_write8(address, reg, value):
+    """Write a single (8bit) register to the device."""
+    msg_w = i2c_msg.write(address, [reg, value])
+    i2c_dev.i2c_rdwr(msg_w)
+
+def enter_bootloader(address):
+    print("Entering bootloader...")
+    i2c_write8(address, REG_CTRL, 0xA0)
+    i2c_write8(address, REG_DEBUG, 0xA3)
+    time.sleep(0.1)
+
+def set_default_boot(target):
+    i2c_write8(bootloader_i2c_addr, REG_BOOTLOADER_CMD, target)
+    time.sleep(0.02)
+
+def set_default_boot_bootloader():
+    set_default_boot(2)
+    print("Changed default boot to bootloader")
+
+def set_default_boot_main_program():
+    set_default_boot(4)
+    print("Changed default boot to main program")
+
+
+def get_chip_id(address):
+    """Get the IOE chip ID."""
+    return (i2c_read8(address, REG_CHIP_ID_H) << 8) | i2c_read8(address, REG_CHIP_ID_L)
+
+def confirm_id(address, id):
+    chip_id = get_chip_id(address)
+    print(f"confirming I2C:{hex(address)}, Chip ID:{hex(id)}, Read ID:{hex(chip_id)}")
+    assert( chip_id == id )
+
+def confirm_bootloader_version(version):
+    assert( i2c_read8(bootloader_i2c_addr, REG_VERSION) == version )
+    print("confirmed bootloader version", version)
+
+def set_flash_page(page):
+    i2c_write8(bootloader_i2c_addr, REG_FLASH_PAGE, page)
+    # print "Page set to", page
+
+def write_page_to_aprom():
+    i2c_write8(bootloader_i2c_addr, REG_CTRL, MASK_CTRL_FWRITE)
+    while True:
+        time.sleep(0.01)
+        try:
+            i2c_read8(bootloader_i2c_addr, 0x00)
+            break
+        except:
+            print("waiting for page write to finish...")
+
+def read_page_from_aprom():
+    i2c_write8(bootloader_i2c_addr, REG_CTRL, MASK_CTRL_FREAD)
+    time.sleep(0.001)
+
+def jump_to_main_program():
+    i2c_write8(bootloader_i2c_addr, REG_BOOTLOADER_CMD, 1)
+    print("Jumped to start main program execution")
+
+
+def firmware_update(bin_data, i2c_address, chip_id):
+    assert( len(bin_data) % PAGE_SIZE == 0)
+    assert( PAGE_SIZE <= len(bin_data) <= flash_size)
+
+    try:
+        i2c_read8(bootloader_i2c_addr, 0x00)
+    except:
+        # We're not in bootloader yet, let's enter first
+        confirm_id(i2c_address, chip_id)
+        enter_bootloader(i2c_address)
+
+    # Ok, we should be in bootloader now
+
+    # Ensure bootloader is running with 24MHz clock
+    assert( i2c_read8(bootloader_i2c_addr, 0xF7) & 0x10 )
+
+    confirm_id(bootloader_i2c_addr, bootloader_id)
+    confirm_bootloader_version(bootloader_version)
+
+    set_default_boot_bootloader()
+
+    # Flash the program!
+    for page in range(len(bin_data)//PAGE_SIZE):
+        i=0
+        # for i in range(PAGE_SIZE):
+        while i<PAGE_SIZE:
+            start_offset = page*PAGE_SIZE + i
+            next_offset   = page*PAGE_SIZE + i + I2C_WRITE_MAX_SIZE
+            # print("Writing bytes from", start_offset, "to", next_offset-1)
+            i2c_write_bytes( bootloader_i2c_addr, REG_APROM_FLASH+i, bin_data[ start_offset : next_offset ] )
+            i += I2C_WRITE_MAX_SIZE
+            # i2c_write8(bootloader_i2c_addr, REG_APROM_FLASH+i, bin_data[page*PAGE_SIZE + i])
+        set_flash_page(page)
+        write_page_to_aprom()
+        print(f"Page {page} written to APROM")
+
+    print("Code written, verifying...")
+    for page in range(len(bin_data)//PAGE_SIZE):
+        print("Verifying page", page)
+        set_flash_page(page)
+        read_page_from_aprom()
+        # for i in range(PAGE_SIZE):
+        i=0
+        while i< PAGE_SIZE:
+            read_length  = min(I2C_WRITE_MAX_SIZE, PAGE_SIZE-i)
+            read_data = i2c_read_bytes(bootloader_i2c_addr, REG_APROM_FLASH+i, read_length)
+
+            start_offset = page*PAGE_SIZE + i
+            wr_data = bin_data[ start_offset : start_offset+read_length ]
+
+            # print("read_data, wr_data", read_data)
+            # print (wr_data)
+
+            if (read_data != wr_data):
+                print("Flash verification failed, exiting..")
+                return
+            i += read_length
+
+    print("Flash verified, setting the newly flashed program as the default boot option and running it...")
+
+    set_default_boot_main_program()
+
+    jump_to_main_program()
+
+
+
+if __name__ == "__main__":
+    filename = sys.argv[1];
+    # if bin_filename.endswith(".bin"):
+    #     bin_data = open(bin_filename, "rb").read()
+    #     bin_data = [ord(x) for x in bin_data]
+    # elif bin_filename.endswith(".hex"):
+
+    from intelhex import IntelHex
+    ih = IntelHex()
+    ih.fromfile(filename,format='hex')
+
+    target_i2c    =  ih[200000]
+    target_chipid =  ih[200001]
+    target_chipid += ih[200002] << 8
+    nuvoton_class =  ih[200003]
+    saved_crc     =  ih[200004]
+    saved_crc     += ih[200005] << 8
+
+    assert( nuvoton_class in [16, 32] )
+
+    if nuvoton_class == 32:
+        bootloader_id       = 0xB004
+        bootloader_version  = 211
+        flash_size          = 32768-2048
+
+    del ih[200004]
+    del ih[200005]
+
+    bin_data = list(ih.tobinarray())
+    crc = binascii.crc_hqx(bytearray(bin_data), 0)
+
+    # print("crc, saved_crc", hex(crc), hex(saved_crc))
+    assert( saved_crc == crc )
+
+    for addr in range(200000, 200004):
+        del ih[addr]
+
+    bin_data = list(ih.tobinarray())
+
+    print("Firmware length", len(bin_data))
+    # print(repr(bin_data[:30]))
+
+    # chip_id      = int( bin_filename.split(".")[0].split("_")[-1] , 16)
+    # i2c_address  = int( bin_filename.split(".")[0].split("_")[-2] , 16)
+    # file_crc     = int( bin_filename.split(".")[0].split("_")[-3] , 16)
+    # crc = binascii.crc_hqx(str(bin_data), 0)
+    # print("Calculated CRC:", hex(crc))
+    # assert( file_crc == crc )
+
+    firmware_update(bin_data, target_i2c, target_chipid)

firmware/readme.md

@@ -0,0 +1,114 @@
+# Inventor HAT Mini - Firmware Flashing
+
+## Issue
+
+It was recently reported that a number of [Inventor HAT Mini](https://shop.pimoroni.com/products/inventor-hat-mini) boards were unable to read
+the encoders of any connected motors, instead returning zero. After much investigation it was discovered that these boards had been flashed
+at our factory with an older firmware version than what was intended, that lacked the encoder subsystem. All other features of the boards are unaffected.
+
+If you encounter this issue with your board, you can either reflash the board yourself using the instructions below, or reach out to Pimoroni support for a replacement at `support@pimoroni.com` (or via the form at https://pimoroni.freshdesk.com/support/tickets/new)
+
+## Instructions
+
+To be able to flash your Inventor HAT Mini, it needs its I2C address to be `0x16`. By default Inventor HAT Mini ships with address `0x17`, so this will need to be changed before flashing, and then changed back afterwards.
+
+### Identify Address
+
+First, identify your board's I2C address. This can be done by running `i2cdetect -y 1` on your Pi. You should see a printout similar to this:
+
+```
+     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
+00:                         -- -- -- -- -- -- -- --
+10: -- -- -- -- -- -- -- 17 -- -- -- -- -- -- -- --
+20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+70: -- -- -- -- -- -- -- --
+```
+
+This confirms the board has address `0x17`.
+
+### Change Address
+
+Next, change the board's address by running the `set_i2c_address.py` script that is in this directory.
+
+```
+python3 ./set_i2c_address 0x17 0x16
+```
+
+You should see an output similar to this:
+```
+Waiting for flash writing to start..
+flash write ongoing
+flash write ongoing
+...
+flash write ongoing
+flash write ongoing
+flash write finished
+```
+
+:information-source: If you see `flash write ongoing` printed out repeatedly for more than a few seconds, it is likely the address changed worked but the acknowledgement was missed. So cancel the program by pressing CTRL+C on your keyboard.
+
+Run `i2cdetect -y 1` again to confirm the change:
+
+```
+     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
+00:                         -- -- -- -- -- -- -- --
+10: -- -- -- -- -- -- 16 -- -- -- -- -- -- -- -- --
+20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+70: -- -- -- -- -- -- -- --
+```
+
+### Flash the Firmware
+
+With the Inventor HAT Mini having an address of `0x16` it can now be flashed. To do this run the `firmware_update.py` script that is in this directory, giving it the firmware file:
+
+:warning: You will need to `pip install intelhex` for this to work
+
+```
+python ./firmware_update.py  "super_io.fw"
+```
+
+You should see an output similar to this:
+
+```
+Firmware length 30720
+confirming I2C:0x16, Chip ID:0x510e, Read ID:0x510e
+Entering bootloader...
+confirming I2C:0x6f, Chip ID:0xb004, Read ID:0b004
+confirmed bootloader version 211
+Changed default boot to bootloader
+Page 0 written to APROM
+Page 1 written to APROM
+...
+Page 238 written to APROM
+Page 239 written to APROM
+Code written, verifying...
+Verifying page 0
+Verifying page 1
+...
+Verifying page 238
+Verifying page 239
+Flash verified, setting the newly flashed program as the default boot option and running it...
+Changed default boot to main program
+Jumped to start main program execution
+```
+
+If you get an error message like `Flash verification failed, exiting..`, try re-running the firmware update command again. If it still fails, reach out to Pimoroni support.
+
+
+### Restoring the Address
+
+With the firmware successfully flashed, the Inventor HAT Mini's address can be restored back to `0x17` (or any other value you wish to use) by following the same steps as in the [Change Address](#change-address) step but with the values reversed:
+
+```
+python ./set_i2c_address 0x16 0x17
+```
+
+Now your Inventor HAT Mini has been flashed with the latest firmware, letting its encoders be used.