Loading files
e838b84e2This file is pinned to the selected release. Download the original to open it in your design tool.
/*
* Copyright 2026 Scott Bezek
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* FaderBuddy I2C bootloader protocol.
*
* Shared between the bootloader (firmware/bootloader/), the application
* (firmware/src/), and any I2C host that drives firmware updates (ESPHome
* component, production jig, WebHID tool). See ABOUT_I2C_BOOTLOADER.md.
*
* All multi-byte fields are big-endian (MSB first), matching i2c_data.h.
*/
#pragma once
#include <stdint.h>
/* ---------------------------------------------------------------------------
* Flash memory map (ATtiny1616: 16 KB flash, 64-byte pages, 256 pages)
* ------------------------------------------------------------------------- */
#define BL_FLASH_SIZE (16384U)
#define BL_PAGE_SIZE (64U)
#define BL_MAPPED_FLASH_BASE (0x8000U) /* flash mapped into data space */
/*
* Boot section size, in 256-byte units == FUSE.BOOTEND. The application is
* linked to start at BL_APP_START (== BOOTEND * 256) and the same value is
* written to the BOOTEND fuse. This is the single source of truth for the
* boot/app split -- keep this constant, the app's linker offset, the fuse, and
* the host-side image extractors in lockstep. All of them:
* - platformio.ini: board_build.text_section_start, and --bootend in the
* fb_bootloader_only / fb_app_and_bootloader upload commands
* - firmware/tools/export_app_image.py: FLASH_START
* - production_tools/programAndTest/tools/generate_app_image.py: FLASH_START
* - production_tools/programAndTest/test_host.py: the --bootend argument
* - production_tools/programAndTest/factory_test_images/ (rebuild the image)
*
* Sized to the measured bootloader: 1402 bytes as built, so 0x06 (1536) is the
* smallest 256-byte-granular section that holds it, leaving ~134 bytes of
* bootloader headroom. The app needs the rest -- at 0x07 it no longer links.
*
* Changing this is a UPDI-only operation (fuse write), and the boot section is
* unwritable by the CPU in any case, so a board in the field cannot be moved to
* a different split over I2C. See ABOUT_I2C_BOOTLOADER.md.
*/
#define BL_BOOTEND (0x06)
#define BL_APP_START ((uint16_t)(BL_BOOTEND) * 256U) /* 0x0600 */
#define BL_APP_SIZE (BL_FLASH_SIZE - BL_APP_START)
#define BL_APP_END (BL_FLASH_SIZE - 1U) /* last app byte */
#define BL_APPEND (0x00) /* FUSE.APPEND: app section runs to end of flash */
/*
* Fixed-address app metadata footer: the last 2 bytes of flash, holding the
* app's FW_VERSION as big-endian bytes (see firmware/src/main.cpp,
* FW_VERSION_FOOTER). Because APPEND runs the app section to FLASHEND
* regardless of app size, this address never moves as the app grows --
* unlike a footer placed relative to the app's own end, it needs no rebuild
* bookkeeping. A host (e.g. the ESPHome component) packaging a raw app image
* for the I2C bootloader can read the version straight from the last 2 bytes
* of that image, with no risk of drifting from what the flashed app will
* actually report via REG_FW_VERSION -- both come from the same FW_VERSION
* macro at compile time. Placed via `-Wl,--section-start=.fw_meta=...` in
* platformio.ini (env:fb_app_only); NOT consumed by the bootloader itself.
* ------------------------------------------------------------------------- */
#define BL_APP_META_ADDR (BL_FLASH_SIZE - 2U) /* 0x3FFE */
/* ---------------------------------------------------------------------------
* I2C addressing
*
* The bootloader answers on the same address as the application: base 0x20 plus
* the 3-bit hardware address from the jumpers, so a fader keeps its bus identity
* in bootloader mode.
*
* The port bits are REVERSED relative to the address bits -- the board nets are
* PC0 = A2, PC1 = A1, PC2 = A0 -- and a jumper pulls its pin low, so a fitted
* jumper sets its bit. Both the application (setup_i2c() in
* firmware/src/main.cpp) and the bootloader (twi_slave_init()) must decode it
* the same way, or a fader changes address when it enters the bootloader.
* ------------------------------------------------------------------------- */
#define BL_I2C_BASE_ADDRESS (0x20)
/* ---------------------------------------------------------------------------
* REG_VERSION (0x00) response
*
* Reading register 0x00 is the universal "who are you" probe:
* - a valid protocol version (>= 5) -> application is running
* - BL_VERSION_MARKER -> bootloader is resident (no usable app)
* - NAK / no response -> device absent or wedged
* The marker is chosen outside any valid protocol version and != 0xFF.
* ------------------------------------------------------------------------- */
#define BL_VERSION_MARKER (0xB0)
/* Bootloader implementation version, reported by BL_CMD_GET_VERSION_CRC16. */
#define BL_BOOTLOADER_VERSION (0x01)
/* ---------------------------------------------------------------------------
* Bootloader command set (first byte of an I2C write is the opcode)
* ------------------------------------------------------------------------- */
#define BL_CMD_SET_PAGE_ADDR (0x01) /* + u16 flash page addr (section offset) */
#define BL_CMD_SEND_FRAME (0x02) /* + 16 data bytes + u16 crc16 */
#define BL_CMD_RUN_APP (0x03) /* leave bootloader, start the application */
#define BL_CMD_ERASE_APP (0x04) /* erase the whole application section */
#define BL_CMD_GET_STATUS (0x05) /* read back: [version, status, last_error] */
#define BL_CMD_GET_VERSION_CRC16 (0x06) /* + u16 addr + u16 len -> [version, crc_hi, crc_lo] */
/* SEND_FRAME geometry: 4 frames of 16 data bytes fill one 64-byte page. */
#define BL_FRAME_DATA_LEN (16U)
#define BL_FRAMES_PER_PAGE (BL_PAGE_SIZE / BL_FRAME_DATA_LEN) /* 4 */
/* Status byte values returned by BL_CMD_GET_STATUS (byte 1). */
#define BL_STATUS_IDLE (0x00) /* resident, ready for a command */
#define BL_STATUS_NO_APP (0x01) /* resident because the app is invalid/blank */
/* Error codes returned by BL_CMD_GET_STATUS (byte 2); cleared by SET_PAGE_ADDR. */
#define BL_ERR_NONE (0x00)
#define BL_ERR_CRC (0x01) /* SEND_FRAME payload CRC mismatch */
#define BL_ERR_ADDR_RANGE (0x02) /* target page outside the app section */
#define BL_ERR_FRAME_SEQ (0x03) /* SEND_FRAME without a preceding SET_PAGE_ADDR */
#define BL_ERR_NVM (0x04) /* NVMCTRL reported WRERROR */
/* ---------------------------------------------------------------------------
* Warm-reset entry token
*
* To ask a running application to drop into the bootloader, the host writes
* REG_ENTER_BOOTLOADER; the app stores BL_ENTRY_TOKEN_MAGIC at a fixed .noinit
* RAM address, then issues a software reset. The bootloader (which owns the
* reset vector) reads the token plus the software-reset flag to decide whether
* to stay resident.
*
* The token lives at a FIXED absolute RAM address so the two independently
* linked binaries agree on it. It is deliberately NOT at the very top of RAM:
* the stack starts at RAMEND (0x3FFF) and grows down, so a token there would be
* clobbered by the bootloader's own startup pushes. 0x3F00 leaves 255 bytes of
* stack headroom (ample for the tiny bootloader) while staying well above both
* binaries' .data/.bss (which grow up from RAMSTART 0x3800).
* ------------------------------------------------------------------------- */
#define BL_ENTRY_TOKEN_ADDR (0x3F00)
#define BL_ENTRY_TOKEN_MAGIC (0xB007F00DUL)
#define BL_ENTRY_TOKEN (*(volatile uint32_t *)(BL_ENTRY_TOKEN_ADDR))
/* ---------------------------------------------------------------------------
* CRC16-CCITT (poly 0x1021, init 0xFFFF, no input/output reflection).
* Used for per-frame integrity and whole-image verification.
* ------------------------------------------------------------------------- */
static inline uint16_t bl_crc16_update(uint16_t crc, uint8_t data) {
crc ^= (uint16_t)data << 8;
for (uint8_t i = 0; i < 8; i++) {
if (crc & 0x8000) {
crc = (uint16_t)((crc << 1) ^ 0x1021);
} else {
crc = (uint16_t)(crc << 1);
}
}
return crc;
}
#define BL_CRC16_INIT (0xFFFF)