dualbank – Dualbank Module

The dualbank module adds ability to update and switch between the two identical app partitions, which can contain different firmware versions.

Having two partitions enables rollback functionality.

The two partitions are defined as the boot partition and the next-update partition. Calling dualbank.flash() writes the next-update partition.

After the next-update partition is written a validation check is performed and on a successful validation this partition is set as the boot partition. On next reset, firmware will be loaded from this partition.

Use cases:
  • Can be used for OTA Over-The-Air updates.

  • Can be used for dual-boot of different firmware versions or platforms.

Note

Boards with flash =2MB:

This module is unavailable as the flash is only large enough for one app partition.

Boards with flash >2MB:

This module is enabled/disabled at runtime based on whether the CIRCUITPY drive is extended or not. See storage.erase_filesystem() for more information.

import dualbank

dualbank.flash(buffer, offset)
dualbank.switch()

Available on these boards
  • 01Space 0.42 OLED ESP32C3
  • AITHinker ESP32-C3S_Kit
  • ATMegaZero ESP32-S2
  • Adafruit Feather ESP32 V2
  • Adafruit Feather ESP32S3 No PSRAM
  • Adafruit HUZZAH32 Breakout
  • Adafruit ItsyBitsy ESP32
  • Adafruit MatrixPortal S3
  • Adafruit Metro ESP32S3
  • Adafruit QT Py ESP32 PICO
  • Adafruit QT Py ESP32-S3 no psram
  • Adafruit QT Py ESP32C3
  • Adafruit-Qualia-S3-RGB666
  • Arduino Nano ESP32
  • BLING!
  • BPI-Leaf-S3
  • BPI-PicoW-S3
  • Bee-Data-Logger
  • Bee-Motion-S3
  • Bee-S3
  • BlizzardS3
  • CRCibernetica IdeaBoard
  • ColumbiaDSL-Sensor-Board-V1
  • Cytron Maker Feather AIoT S3
  • DFRobot Beetle ESP32-C3
  • DFRobot FireBeetle 2 ESP32-S3
  • Deneyap Kart
  • Deneyap Kart 1A
  • Deneyap Kart 1A v2
  • Deneyap Kart G
  • Deneyap Mini
  • Deneyap Mini v2
  • ES3ink
  • ESP32 Devkit V1
  • ESP32-C3-DevKitM-1
  • ESP32-C6-DevKitC-1-N8
  • ESP32-C6-DevKitM-1
  • ESP32-S2-DevKitC-1-N8R2
  • ESP32-S3-Box-2.5
  • ESP32-S3-Box-Lite
  • ESP32-S3-DevKitC-1-N32R8
  • ESP32-S3-DevKitC-1-N8
  • ESP32-S3-DevKitC-1-N8R2
  • ESP32-S3-DevKitC-1-N8R8
  • ESP32-S3-DevKitC-1-N8R8-with-HACKTABLET
  • ESP32-S3-DevKitM-1-N8
  • ESP32-S3-EYE
  • ESP32-S3-USB-OTG-N8
  • Espressif ESP32 DevKitc V4 WROOM-32E
  • Espressif ESP32 DevKitc V4 WROVER
  • Espressif ESP32-EYE
  • Espressif ESP32-LyraT
  • Espressif-ESP32-S3-LCD-EV-Board
  • FeatherS2
  • FeatherS2 PreRelease
  • FeatherS3
  • Hardkernel Odroid Go
  • Heltec ESP32-S3-WIFI-LoRa-V3
  • IoTs2
  • LILYGO T-DECK
  • LILYGO T-DISPLAY S3 v1.2
  • LILYGO TEMBED ESP32S3
  • LILYGO TTGO T-DISPLAY v1.1
  • LILYGO TTGO T-DISPLAY v1.1 4M
  • LILYGO TTGO T-OI PLUS
  • LOLIN S3 16MB Flash 8MB PSRAM
  • LOLIN S3 PRO 16MB Flash 8MB PSRAM
  • Lilygo T-watch 2020 V3
  • Luatos Core-ESP32C3
  • M5 Stack Cardputer
  • M5STACK STAMP-C3
  • M5Stack Atom Echo
  • M5Stack Atom Lite
  • M5Stack Atom Matrix
  • M5Stack Atom U
  • M5Stack AtomS3
  • M5Stack AtomS3 Lite
  • M5Stack AtomS3U
  • M5Stack Core Basic
  • M5Stack Core Fire
  • M5Stack Core2
  • M5Stack CoreS3
  • M5Stack Dial
  • M5Stack M5Paper
  • M5Stack Stick C
  • M5Stack Stick C Plus
  • M5Stack Timer Camera X
  • Maker Go ESP32C3 Supermini
  • MakerFabs-ESP32-S3-Parallel-TFT-With-Touch-7inch
  • MicroDev microC3
  • MicroDev microS2
  • NanoS3
  • Neuron
  • Oxocard Artwork
  • Oxocard Connect
  • Oxocard Galaxy
  • Oxocard Science
  • ProS3
  • SQFMI Watchy
  • Seeed Studio XIAO ESP32C3
  • Sunton ESP32-2424S012
  • Sunton-ESP32-8048S070
  • TinyC6
  • TinyPICO
  • TinyPICO Nano
  • TinyS3
  • TinyWATCH S3
  • VCC-GND YD-ESP32-S3 (N16R8)
  • VCC-GND YD-ESP32-S3 (N8R8)
  • Waveshare ESP32-S3-GEEK
  • Waveshare ESP32-S3-Pico
  • Waveshare ESP32S3 LCD 1.28
  • WeAct ESP32-C6 (4MB)
  • WeAct ESP32-C6 (8MB)
  • WeMos LOLIN32 Lite
  • Wemos Lolin C3 Mini" // from Wemos MP
  • Wemos Lolin C3 Pico" // from Wemos MP
  • sunton_esp32_2432S028

dualbank.flash(buffer: circuitpython_typing.ReadableBuffer, offset: int = 0) None

Writes one of the two app partitions at the given offset.

This can be called multiple times when flashing the firmware in smaller chunks.

Parameters:
  • buffer (ReadableBuffer) – The entire firmware or a partial chunk.

  • offset (int) – Start writing at this offset in the app partition.

dualbank.switch() None

Switches to the next-update partition.

On next reset, firmware will be loaded from the partition just switched over to.