Rehydrator

Rehydrator

Rehydrator is a compact reference project for building Contiki-NG firmware images for TI CC1352R boards and placing them into a TI BIM/OAD compatible flash layout.

Persistent fallback slot | User/update slot | Broken image test | Linker-script based placement | UniFlash programming

Setup | Quick Start | Flashing | Monitor | Documentation

Overview

This repository demonstrates how to place two executable firmware slots in the same CC1352R flash memory while keeping a persistent fallback image available.

Image	Flash region	Purpose
old-firmware	0x00030000	Persistent fallback firmware
new-firmware	0x00000000	Valid user/update firmware
new-firmware-broken	0x00000000	Invalid IMGID test image written over the user/update slot

After reset, TI BIM first checks the user image at page 0. If it is valid, new-firmware runs. If it is invalid, BIM falls back to old-firmware.

Scope Limitation

Rehydrator is intentionally limited to the two-image on-chip BIM model provided by TI: one user/update image and one persistent fallback image. It does not implement a production-style multi-image rollback manager with shared NVM state, boot-attempt counters, health confirmation, or automatic promotion/demotion of more than two firmware images.

new-firmware-broken is therefore not a third bootable slot. It is only a test artifact that is flashed into the same 0x00000000 user/update region to prove that BIM rejects an invalid image and returns to old-firmware.

If a third firmware image is added to flash without extending BIM or adding a separate recovery/activation layer, the current boot flow will not know how to select it, track its history, or fall back through the previous two images. In that case the extra image is just stored data from BIM's point of view, not an active participant in the fallback mechanism.

Setup

Linux or WSL is recommended. On Windows, WSL Ubuntu is the most practical option for the build and verification scripts.

1. Install required tools

Ubuntu/WSL:

sudo apt update
sudo apt install -y git make python3 gcc-arm-none-eabi binutils-arm-none-eabi picocom

Install TI UniFlash for programming the board:

https://www.ti.com/tool/UNIFLASH

2. Download Contiki-NG

git clone --recursive https://github.com/contiki-ng/contiki-ng.git

If this project is placed under contiki-ng/examples/rehydrator, the default CONTIKI ?= ../.. value in the Makefile works directly.

If the project is stored elsewhere, pass the Contiki-NG path explicitly:

make CONTIKI=/path/to/contiki-ng TARGET=simplelink BOARD=sensortag/cc1352r1 upload-files

3. Hardware requirements

Component	Note
TI CC1352R-based LPSTK/SensorTag board	Target board: sensortag/cc1352r1
XDS110 or compatible debugger	Used by UniFlash for programming
USB serial connection	Used for runtime logs

Quick Start

Build the fallback and valid update images:

make TARGET=simplelink BOARD=sensortag/cc1352r1 upload-files

Generated core artifacts:

upload/old-firmware.hex
upload/new-firmware.hex
upload/old-firmware.bin
upload/new-firmware.bin
upload/manifest.txt

Build the intentionally broken image used for fallback testing:

make TARGET=simplelink BOARD=sensortag/cc1352r1 new-firmware-broken-upload-files

Verify the ELF layout and OAD image headers:

scripts/verify-layout.sh

Flashing

Recommended normal test order:

1. bim/bim_onchip.hex
2. upload/old-firmware.hex
3. Reset -> old-firmware runs
4. upload/new-firmware.hex
5. Reset -> new-firmware runs

Fallback test order:

1. bim/bim_onchip-trace.hex
2. upload/old-firmware.hex
3. upload/new-firmware-broken.hex
4. Reset -> BIM rejects the user image and runs old-firmware

Use .hex files with UniFlash when possible. HEX files include address records, which reduces the risk of programming an image at the wrong base address.

Caution

Do not perform a full chip erase. Sector 43 contains BIM + CCFG and should only be erased when you intentionally reprogram BIM.

Monitor

Monitor board logs with:

picocom -b 115200 --imap lfcrlf /dev/ttyACM0

Expected application logs:

[OLD-FW] heartbeat
[NEW-FW] heartbeat

The serial device name may differ by system. Check /dev/ttyACM1 or /dev/ttyUSB0 if needed.

If serial access is denied, add the current user to the dialout group:

sudo usermod -aG dialout $USER

Flash Map

0x00000000 +----------------------+
           | User / Update Image  | pages 0 - 23
0x00030000 +----------------------+
           | Persistent Fallback  | pages 24 - 40
0x00052000 +----------------------+
           | Metadata             | page 41
0x00054000 +----------------------+
           | Recovery             | page 42
0x00056000 +----------------------+
           | BIM + CCFG           | page 43
0x00058000 +----------------------+

Test Scenarios

Scenario	Programmed images	Expected result
Fallback only	BIM + old-firmware	[OLD-FW] heartbeat
Valid update	BIM + old-firmware + new-firmware	[NEW-FW] heartbeat
Broken IMGID	Trace BIM + old-firmware + new-firmware-broken	BIM rejects the broken image, [OLD-FW] heartbeat

Project Structure

Path	Description
src/	Firmware sources and OAD header implementations
include/	OAD header, flash layout, and project configuration
linker/	Linker scripts for the user and fallback slots
scripts/verify-layout.sh	Post-build layout verification helper
bim/	Reference BIM HEX files and license notice
docs/	Detailed technical documentation and report files
Makefile	Main build and upload artifact entry point

Documentation

Topic	English	Turkish
Flash layout	docs/en/flash-layout.md	docs/tr/flash-layout.md
Build and verification	docs/en/build-and-verification.md	docs/tr/build-and-verification.md
UniFlash guide	docs/en/uniflash-guide.md	docs/tr/uniflash-guide.md
BIM notes	docs/en/bim-onchip-notes.md	docs/tr/bim-onchip-notes.md
Glossary	docs/en/glossary.md	docs/tr/glossary.md

Notes

bim/bim_onchip.hex and bim/bim_onchip-trace.hex are reference BIM artifacts. Before redistributing them, check the license terms of the corresponding TI SimpleLink SDK/BIM source.

Team

Name	LinkedIn
Haris Elhalefi	elharis-halef
Yasin Engin	yasin-engin