Tanmatsu

• 1: Tanmatsu: getting started
• 1.1: Compiling the template app
• 2: Tanmatsu: hardware
• 2.1: Tanmatsu: connectors
• 2.1.1: Tanmatsu: external add-on port
• 2.1.1.1: SAO adapter
• 2.1.2: Tanmatsu: internal add-on port
• 2.2: Tanmatsu: specifications
• 2.3: Tanmatsu: 3D printed case
• 3: Tanmatsu: software
• 3.1: AppFS
• 3.2: BadgeLink
• 3.3: Meshtastic

1 - Tanmatsu: getting started

Introduction

Congratulations! You just got your hands on your Tanmatsu, we bet you’re excited to get started so let’s not delay and get right to it!

Turning Tanmatsu on and off

The top most button on the right side of the device is the power button.

Tanmatsu has multiple power states, some are defined by software, others by hardware. Depending on the state your device is in you will need to hold down the power button for a different duration to reach the desired state.

• If your Tanmatsu is completely turned off it is in a mode where only the clock is running. This mode requires so little power that you should not notice any battery drain in years if the device is left alone. Pressing the power button for 2.5 seconds turns the device on if it is in this state.
• If your Tanmatsu is turned on you can turn it off completely by holding down the power button for more than half a second.
• If you keep holding down the power button after the device has powered off then the device will restart 2.5 seconds after it powered off. This allows for easily rebooting your tanmatsu by holding down the power button for 3 seconds.
• Depending on the app currently running on your Tanmatsu there might be more power states available. We recommend trying a short press of the power button to enter and leave the sleep state.

Charging your Tanmatsu

You can charge your Tanmatsu by plugging in a power source (phone charger or computer) into the USB-C port. Tanmatsu will automatically power on when a power source is detected and battery charging will start automatically.

Tanmatsu will only charge when on or in sleep mode. If Tanmatsu is powered off the battery will not be charged even with a power source connected to the USB-C port. The default firmware for Tanmatsu will include a mode which turns off the radio and display and keyboard backlight before putting the ESP32-P4 application processor into deep sleep mode. You can enter this mode by pressing the power button for less than half a second. You can check if your Tanmatsu is charging by looking at the color of the power LED.

Power LED

The color of the power LED indicates the state of the power management system.

If the power LED displays a solid single color:

• Blue: running on battery, no charger detected
• Yellow: charger detected, battery is being charged
• Green: charger detected, battery is fully charged
• Red: charger detected, no battery detected

If the power LED displays a blinking color:

• Slowly blinking red: the battery is almost empty, connect a charger to avoid losing work
• Rapidly blinking red: a fault occured in the power management circuit

In case you encounter a fault condition please exit the currently running app and return to the launcher menu. The launcher menu will provide more detailed information about the active fault flags.

PMIC status LED

There is a small red LED on the back of the mainboard. This LED provides additional status information about the state of the power management system of Tanmatsu.

• Off: the battery is not being charged
• Slow blinking: a PMIC fault has occured
• Rapid bliniing: Tanmatsu is trying to charge the battery but no battery is being detected

PMIC stands for “Power Management Integrated Circuit”. Tanmatsu uses a BQ25895 PMIC from Texas Instruments to manage battery charging.

Fault conditions

A fault doesn’t immediately mean there is anything wrong with your Tanmatsu and using a Lithium Polymer battery is not dangerous if the battery is handled correctly. Tanmatsu contains a multiple layers of protection to prevent any damage to your device, the battery or it’s surroundings. If charging is stopped due to a fault then most likely there is something wrong with your battery, though this doesn’t immediately have to be a problem.

The protection functions built into the Tanmatsu mainboard will, in addition to the battery protection circuit built into the battery itself, stop charging if it detects that the battery voltage is below the minimum safe threshold for a Lithium Polymer battery or above the maximum voltage threshold of a Lithium Polymer battery. In both cases the power LED will rapidly blink in red and the small red LED on the back of the mainboard will

A situation that can trigger the under-voltage protection is a situation where the battery has drained below it’s rated minimum voltage due to degradation when left completely empty for a long period of time. In this situation is is also possible that the battery simply is not detected, in which case the power LED will turn red when an external power source is connected. If the battery has accidently reached a voltage near 2.5 volt then the battery will be disconnected to protect it. Normally the battery voltage recovers a bit automatically after leaving the battery alone for a few minutes. In this situation you can safely restart start charging the battery again after the voltage has reached it’s normal level.

The battery supplied with your Tanmatsu has a built-in protection circuit preventing the battery from draining below it’s minimum rated voltage during normal use.

A Lithium Polymer battery that has reached a voltage below 2.5 volt for a prolonged period of time can become chemically unstable, we recommend replacing the battery if your battery has drained below 2.5 volt. Recharging a Lithium Polymer battery that has been subjected to a situation where it reached a voltage of less than 2.5 volt can be dangerous, the battery may for example swell up and could potentially damage the device or it’s surroundings.

1.1 - Compiling the template app

Setting up the environment on Windows

On Windows we recommend using WSL (Windows Subsystem for Linux) to create a virtual Linux environment to work in.

Step 1: download Ubuntu 24.04.1 LTS from the Microsoft store.

Click the Get button. After the Linux environment is installed you can find it in the start menu.

After starting the Ubuntu environment you should be presented by the following prompt:

Step 2: install required packages

Run the following command to install the dependencies:

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

Press Y when asked if you want to continue.

Step 3: clone the repository

Either clone the template repository or first use the template on Github to set up your own Git repository to work with.

Then clone your repository into the Ubuntu environment:

git clone https://github.com/Nicolai-Electronics/tanmatsu-template-pax

Replace the URL in the command above with the URL of your repository.

Step 4: install the ESP-IDF SDK

First enter the folder into which you have cloned the repository.

cd tanmatsu-template-pax

Then run the following command to install ESP-IDF and the toolchain into subfolders of the working folder. The sdk and toolchain folders have been added to the .gitignore file so that they won’t be committed into the repository when you commit your work.

make prepare

Step 5: compile the app

Run the following command to compile the app:

make build

Optionally you can add a DEVICE= argument to select another target device. The default device is Tanmatsu. Currently only Tanmatsu and the MCH2022 badge by Badge.Team are supported.

make build DEVICE=mch2022

Build output can be found in the build/tanmatsu or build/mch2022 folders depending on the selected target.

The binary which can be installed on the target device can be found at build/tanmatsu/application.bin. This is the only file you need to run your app.

You can choose to install your app as the main firmware for the target device, however do note that this will overwrite the launcher and all other already installed data on your device.

Instead of directly flashing the application we recommend using BadgeLink either via a compatible browser or using the commandline utilities to install your application via the USB port.

The BadgeLink tools are not yet available but will be released soon. This page will be updated when the tools have been made available.

2 - Tanmatsu: hardware

This page describes all the hardware on the Tanmatsu main board, explaining how everything is connected.

The ESP32-P4 application processor is the star of the show, this is the processor that will run your applications.

It is directly connected to a lot of peripherals:

• Quad SPI interface to a 16MB flash chip for storing firmware, apps and data
• MIPI DSI and CSI interfaces to the display and camera ports
• Multiple USB interfaces: as device to the USB-C port via the hub and as host to the USB-A port and the internal expansion header
• Multiple SDIO interfaces: to the MMC card reader and the ESP32-C6 radio module
• I2C/I3C interface: to the QWIIC port
• I2C interface: to an I2C bus connecting all the peripherals on the main board to each other

LEDs

Tanmatu has seven LEDs, six of which are addressable RGB LEDs located on the left and right sides of the screen. The seventh LED is located on the back of the board next to the USB-C connector.

The addressable LEDs are fully user controllable by writing the relevant registers of the coprocessor via the internal I2C bus. By default the coprocessor controls the LEDs automatically, this can of course be disabled.

When in automatic control mode the LEDs have the following meaning:

• the “power” LED (top left) indicates the state of the power management subsystem. Blue indicates the device is running on battery power, orange means the battery is being charged via the USB-C connector, green means the battery is fully charged and red means the device is powered via USB but no battery is detected.
• The “radio” LED (middle left) indicates the state of the ESP32-C6 radio module. When the radio module is disabled the LED is off, when the radio module is enabled and running normally the led is green and when the radio module is started in bootloader mode for flashing its firmware the led turns blue.
• The “A” LED (middle right) indicates the state of the USB-A port power output. It is blue when the USB-A port is enabled and off when disabled.
• The “C” LED (top right) turns red when the power button is pressed.

All other LEDs are currently not automatically controlled.

The “message” LED (bottom left) is meant to allow for indicating that an unread message is available to be read, for example after the radio module receives a message via WiFi, BLE, 802.15.4 mesh or LoRa while the ESP32-P4 application processor is running an app.

The “A”, “B” and “C” LEDs are, aside from the above mentioned automatic control states for the “A” and “C” LEDs meant to show custom states defined by the running application.

The seventh LED is a single color red LED located on the back of the device. This LED is controlled by the power management chip and indicates the state of the power circuit.

It is:

• Off when the battery is not charging
• On when the battery is being charged
• Blinks slowly when a fault has occurred (battery charging is automatically stopped)
• Blinks rapidly when it attempts to charge the battery while no battery is attached

Expected behavior is that the LED blinks rapidly for a second when powering the board using the USB-C connector while there is no battery connected before turning off once the coprocessor starts up and instructs the power management chip to stop charging. If the LED continues to blink rapidly this could indicate that the coprocessor is not functioning.

Buttons

Tanmatsu has three buttons on the right side of the device. From top to bottom these buttons have the following functions:

• Power button: hold for two seconds to power on or off the device
• + button: currently unused, mapped to the BSP_INPUT_NAVIGATION_KEY_VOLUME_UP navigation event in the board support package (BSP) software component
• - button: functions as bootloader trigger for the ESP32-P4 when pressed while powering on the device. Otherwise currently unused, mapped to the BSP_INPUT_NAVIGATION_KEY_VOLUME_DOWN navigation event in the board support package (BSP) software component

The + button as well as all the keys of the keyboard on the front of the device are wired up as a diode matrix and connected to the coprocessor. The power button is connected directly to the PMIC power management chip and the state of the power button can be read by the coprocessor. The state of the power button is presented to the application by the board support (BSP) component as the BSP_INPUT_ACTION_TYPE_POWER_BUTTON action event.

The - button is directly connected to GPIO35 of the ESP32-P4 and is mapped to the BSP_INPUT_NAVIGATION_KEY_VOLUME_DOWN navigation event in the board support package (BSP) software component.

All the keyboard buttons are mapped to INPUT_EVENT_TYPE_SCANCODE events by the board support component (BSP), presenting a PC keyboard compatible scancode. In addition the BSP presents the keyboard buttons as INPUT_EVENT_TYPE_NAVIGATION and INPUT_EVENT_TYPE_KEYBOARD events too. Navigation keys trigger the navigation event while the letters and numbers trigger the keyboard event. The keyboard event contains the character on the keyboard button both as ASCII char and UTF-8 string, automatically incorporating the state of the modifier keys (SHIFT and ALT GR).

Connectors

Display connector

Hidden under the front panel a board to board connector connects the display to the main board. The display is pre-installed from the factory so normally you should not need to do anything with this connector.

The connector has the following signals:

• Three MIPI DSI differential pairs (two for data and one for clock)
• 3.3v power for the digital logic in the display
• a 20mA at around 24v supply rail for the backlight LEDs

The output current of the power regulator for the display backlight is controlled by the coprocessor with a PWM signal. You can set the backlight brightness by writing the display backlight brightness register exposed by the coprocessor on the internal I2C bus.

Camera connector

The camera connector is used to connect a CSI camera module. It is pinout-compatible with the camera connector on the Raspberry Pi Zero and 5. Note that software support is limited to a subset of Raspberry Pi compatible camera module sensor chips such as OV5647.

The connector has the following signals:

• Three MIPI CSI differential pairs (two for data and one for clock)
• 3.3v power for the camera module
• Enable signal (shared with the enable signal for the ESP32-C6 radio module)
• LED control signal (shared with internal expansion port pin E2)

USB-C device port

This port is used to charge the battery, to program and debug the ESP32-P4 and ESP32-C6 microcontrollers and to install apps and browse files from your computer.

It is connected to a USB hub chip which splits the USB port into three interfaces:

• ESP32-P4 FS (12Mbit) USB port 1 (by default USB serial / JTAG)
• ESP32-C6 USB serial / JTAG port
• The internal expansion header

By default the ESP32-P4 exposes a USB serial/JTAG debugging peripheral via the USB-C port. This allows for flashing the ESP32-P4 even if no valid firmware is installed.

The firmware on the ESP32-P4 can swap this USB interface with a customizable USB interface, allowing for exposing other interfaces to the host PC. The launcher firmware includes a USB interface called BadgeLink which allows you to manage the device using a set of Python scripts and using WebUSB in the Chrome and Edge browsers.

To force the ESP32-P4 into a bootloader mode simply hold down the third (-) button on the right side of Tanmatsu down while powering on the device. An easy way to do this is to turn off Tanmatsu by pressing the power button until the device turns off, then press and hold the - while plugging in an USB cable into a PC. After plugging in the USB cable the device powers on, the screen will stay black.

USB-A host port

This port can be used to connect a USB device. The 5 volt power output is is limited to 1A of current and protected against short circuits.

The USB-A port can be disabled and enabled by writing the relevant register of the coprocessor via the internal I2C bus. Note that the enable signal for the USB-A port is shared with the boot mode control pin of the ESP32-C6 radio module. When the ESP32-C6 radio gets enabled the USB-A port is forced to power on for a short time and when the ESP32-C6 radio gets put into bootloader mode the USB-A port is forced to power off for a short time.

QWIIC & Stemma QT compatible I2C & I3C connector

This connector can be used to connect external I2C or I3C based accessories. Both Adafruit and Sparkfun make a variety of modules and cables which could be connected to this port.

MMC card slot

Accepts micro SD memory cards including modern high speed SDIO 3.0 cards.

Battery connector

Allows for connecting a single cell Lithium Polymer or Lithium Ion battery cell. Using a protected cell is mandatory. Unprotected cells could potentially be drained below their lowest allowable voltage, which causes damage to the battery. Current control, over voltage protection and proper constant voltage/current charge control are is built-in into the Tanmatsu main board.

Sensor connector

Can be used to connect an optional sensor module.

WiFi, BLE and IEEE802.15.4 radio module

The ESP32-C6 based module provides the board with access to WiFi, BLE and IEEE802.15.4 (mesh network) connectivity while also controlling the LoRa radio module via SPI.

By default the ESP32-C6 module runs a firmware called ESP-Hosted-MCU. This firmware allows the ESP32-P4 to make use of the WiFi and BLE functionality of the radio via the SDIO bus.

Adding support for the 802.15.4 mesh functionality of the ESP32-C6 module and the LoRa radio to the SDIO interface exposed by the ESP-Hosted-MCU firmware is planned.

2.1 - Tanmatsu: connectors

2.1.1 - Tanmatsu: external add-on port

The external expansion port (CATT, for “Connect All The Things”) on Tanmatsu has been designed to be compatible with both PMOD and SAO add-on boards, in addition to it being a port that exposes 8 GPIOs and 3.3v power it can also be used as JTAG interface for the ESP32-P4.

Pinout

Limitations, warnings and hints

• Total for all 3.3v outputs must not exceed 1A of current. It is generally adviced to stay well below this figure.
• Detect pin has a pull-up resistor connected, pull low to enable JTAG functionality for the ESP32-P4
• You can short jumper JP1 to connect pin 13 to the +3.3v rail
• Even if JTAG functioality is selected you can simply initialize a pin as GPIO to use it as such
• If you want to use JTAG via the USB-C port you will need to set the JTAG source manually in software if pin 6 (GPIO34) is being pulled low by an add-on board

2.1.1.1 - SAO adapter

The CATT to SAO adapter is a small adapter board that converts the external add-on port of Tanmatsu into a standard “Simple Add-On” port as found on various event badges.

Assembling the adapter

The recommended method for assembling the adapter board is to start with the male pinheader connecting to Tanmatsu as this component is of lower height than the boxed female header for the SAO side. Make sure that the side of the board with the “CATT SAO” text is the side on which you plug in the connectors, assembling the board upside down will not work.

Pin mapping

Pinout

Photos

2.1.2 - Tanmatsu: internal add-on port

This port is not exposed by default, and a modified back cover needs to be used to make it accessible. For this reason the port is also named the “internal expansion port”.

Pinout

Identification EEPROM

Please include a small EEPROM at address 0x50 on your boards, this will allow Tanmatsu to identify which add-on board has been connected.

The format for the content of this EEPROM has yet to be determined, currently the launcher firmware has no support for identifying add-ons.
The format will most likely be based on the format described here.

Usage

We recommend to start with the GPIOs that do not have shared functions. The following GPIOs on the add-on header can be used without limitations:

E0, E1, E7, E8, E9, E10, E11, E12 and E13

If the built-in LDO number 4 of the ESP32-P4 is enabled (this powers up the SD card slot) then the following GPIOs will be available,
a level shifter is included on the main board so these GPIOs are always using 3.3v voltage level regardless of the SD card operating in 3.3 volt or 1.8 volt mode.

E3, E4, E5 and E6

The following pins can also be used if remapped to GPIO, there might be some activity on these pins during startup or while the launcher is running:

EXT_USB_P, EXT_USB_N, P4_TX and P4_RX

The following pins share functions with other peripherals on the main board. Use these with caution:

E2, I2S_MCLK, I2S_LRCK, I2S_DATA, I2S_SCLK, I3C_SDA and I3C_SCL

Using these pins for other purposes than their intended purpose will render either on-board audio, the QWIIC port or the camera port unusable when the add-on board is plugged in.

Limitations & warnings

• Total for all 3.3v outputs must not exceed 1A of current. It is generally adviced to stay well below this figure.
• Do not exceed a current of 1.5A from the battery when the battery is connected to the internal battery connector
• Do not charge the battery via the internal add-on port

2.2 - Tanmatsu: specifications

This section lists the technical specifications of the Tanmatsu hardware.

Note: information on this page is actively being worked on and might contain accidental errors and inaccuracies.

Physical dimensions

Size of the device including the 3D printed case:

• Width: 12 cm (4.72 in)
• Length: 13.5 cm (5.31 in)
• Height: 1.8 cm (0.71 in)

Weight: 215 g (0.47 pounds) including case and battery

Case

See case.

Peripherals

Display

• Model: SWI LH397K-IC01
• Size: 3.97 in diagonally, 51.84 x 86.40 mm
• Resolution: 480x800
• Colors: 65536 colors (16-bit / RGB565)
• Controller: ST7701S
• Interface: MIPI DSI (2 lanes)
• Brightness: 330cd/m2

Note: display supports 16M colors (24-bit / RGB888) but current software can not make use of this mode.

Nicolai Electronics developed an ESP-IDF component for configuring the MIPI DSI peripheral in the ESP32-P4 for use with this display.
The component also allows for easy switching between the display on the Tanmatsu and the display included with the official ESP32-P4 development kit.

The display will be available as a spare part from our webshop once Tanmatsu is shipped.

Keyboard

• Full 69-key alphanumeric keyboard with colored 6 function keys
• Metal dome sheet for tactile feeling
• LED backlight (white)

The keyboard has been developed by our awesome friends at Solder Party.

The keyboard and corresponding metal dome sheet will be available as a spare part in our webshop once Tanmatsu starts shipping.

Battery

Single cell protected Lithium Polymer battery with PH-2.0 style connector.
The connector and pinout are compatible with the battery connector on Adafruit boards.

The battery will be available as a spare part in our webshop once Tanmatsu starts shipping.

Connectors and interfaces

On the outside of the case:

• USB-C device port connected to an USB hub. Allows access to:
  • The ESP32-P4 USB interface (PHY 1, defaults to USB-serial/JTAG debug interface but can be remapped to custom USB functions by software)
  • ESP32-C6 USB-serial/JTAG debug interface
  • Personality module expansion port (provides access to an optionally connected USB device on a personality module)
• USB-A host port (480 Mbit superspeed USB 2.0), provides 1A of current with automatic current limiting
• Qwiic and Stemma-QT compatible 4-pin SH connector for connecting I2C and I3C accessories
• 3.5 mm headphone jack
• CATT (Connect All The Things) connector: combined PMOD and SAO compatible 2.54 mm pinsocket optionally also usable as JTAG interface for debugging the ESP32-P4 application processor
• Three push buttons (Power, up and down). Holding down the down button when applying power puts the ESP32-P4 into USB download mode for easy firmware recovery
• Micro SD card slot compatible with SDIO 2 and SDIO 3 cards at 3.3v and 1.8v voltage levels
• (optional) SMA antenna connector for LoRa antenna

On the inside of the case:

• PH-2.0 2-pin battery connector
• PicoBlade 2-pin speaker connector for 8 Ohm speaker
• Raspberry Pi camera compatible 22-pin MIPI CSI camera interface
• IPEX-1 antenna connector for LoRa antenna
• Personality module connector: 36-pin 2.54 mm pinsocket with:
  • Access to power rails (5V, Vbatt, Vsys and 3.3v)
  • USB hub downstream port connected to the USB-C port via an USB hub
  • Internal I2C bus (can be used for sensors and for an identification EEPROM)
  • 14 GPIO pins
  • ESP32-P4 USB interface (PHY 2) or 2 extra GPIO pins
  • UART interface or 2 extra GPIO pins
  • I2S interface or 4 extra GPIO pins (shared with audio codec, when used as GPIO audio functionality is unavailable)
  • I3C bus (shared with 4-pin SH connector) or 2 extra GPIO pins

Chips and modules

WiFi, BLE and IEEE 802.15.4 radio

Module: Espressif Systems ESP32-C6-WROOM-1-N8

• CPU: 32-bit RISC-V single core microprocessor, up to 160 MHz
• RAM: 512 KB
• WiFi: WiFi 6 on 2.4GHz
• BLE: 5.3
• Mesh networking: IEEE 802.15.4-2015 protocol, supports Thread 1.3 and Zigbee 3.0
• Flash: 8 MB

More information can be found in the Datasheet.

Application processor

Chip: Espressif Systems ESP32-P4NRW32

• CPU: 32-bit RISC-V dual core microprocessor, up to 400 MHz
• RAM: 32 MB
• Flash: 16 MB

The datasheet for this chip is not yet publicly available

Management coprocessor

Chip: WCH CH32V203C8T6

• CPU: 32-bit RISC-V single core microprocessor, up to 144 MHz
• RAM: 20KB
• Flash: 64 KB

More information can be found in the Datasheet.

The management coprocessor is responsible for reading the keyboard matrix and power management. It presents itself as an I2C peripheral on the internal I2C bus of the Tanmatsu and provides the following services:

• Keyboard events
• PWM control for the display backlight
• PWM control for the keyboard backlight
• Real Time Clock (RTC) backed by watch crystal
• Alarm wakeup
• PMIC control
• Power switching for USB-A port
• Power and boot-mode control for the ESP32-C6 radio module
• Power switching for audio amplifier
• Headphone detection
• Addressable LED control for the 6 built-in addressable LEDs

The firmware for this chip will be made available under terms of the MIT license after the product starts shipping to customers. Modifying the firmware is of course possible but is not recommended.

The firmware of the coprocessor can be updated from the ESP32-P4 application processor, for this Nicolai Electronics developed an ESP-IDF component capable of reprogramming CH32V20x and CH32V30x microcontrollers from the ESP32-P4 application processor.

LoRa radio

The PCB footprint supports a range of radio modules from Ai-Thinker. Software support will initially be provided for the RA-01SH 868 MHz band SX1262 based and the RA-01S 433 MHz band SX1268 based modules.

All Tanmatsu boards will be delivered with a module which has the IPEX-1 antenna connector installed. Optionally an SMA antenna connector can be installed to allow connecting standard external LoRa antennas. Tanmatsu will be provided with either an internal IPEX-1 antenna or a basic SMA antenna depending on the option chosen.

Audio

Everest Semiconductor ES8156 audio codec:

• Hardware volume control via I2C interface
• Stereo audio DAC

FM8002A mono speaker amplifier:

• Can be switched on and off using the coprocessor
• Connected to built-in 8 Ohm speaker

Power management

PMIC

Texas Instruments BQ25895RTW PMIC for battery charging and monitoring as well as DC/DC boost converter for 5 volt rail (to power USB-A port, addressable LEDs and 5 volt pin on the personality module expansion header).

Provides soft power on/off functionality when the device is battery powered and allows seamless transition between battery and USB-C power source.

3.3v rail DC/DC converter

Texas Instruments TPS63020DSJR DC/DC buck and boost converter providing a stable 3.3v rail even when the battery voltage drops below 3.3 volt.

Backlight drivers

Two AP3032KTR backlight driver chips, one for the display and one for the keyboard backlight LEDs.
Brightness controlled using PWM via the CH32V203 coprocessor.

Standby power rail

A small LDO provides 2.5v to the Vbatt rail of the CH32V203 coprocessor even when the device is off. This uses almost no power (theoretically the battery would last over 10 years on a single charge if the device is never turned on, ignoring LiPo battery self-discharge) and allows the Real Time Clock in the CH32V203 coprocessor to keep track of time even when the device is off. A special latch circuit circuit allows the CH32V203 to power on the Tanmatsu using its alarm pulse output by emulating a press of the power button.

Addressable LEDs

Six SK6805-EC20 addressable LEDs controlled by the coprocessor.

Sensors

• Bosch BMI270 IMU combined accelerometer and gyroscope
• Header for optional SCD40 or SCD41 CO2, temperature and humidity sensor (not populated, modules are available on AliExpress) or other I2C controlled sensor

Questions?

If you have questions please contact us by joining one of our community chatgroups (Telegram and Discord) or by emailing us.

2.3 - Tanmatsu: 3D printed case

Information about the 3D printed case for Tanmatsu.

Note: information on this page is actively being worked on and might contain accidental errors and inaccuracies.

Filament

The 3D printed case and spacer are printed using Extrudr PLA NX2 on Prusa Mini and Prusa XL printers.

Design files

Once Tanmatsu is available the spacer and case designs will be published as STEP and STL files.

The 3D printed case and spacer will both be available as a spare part from our webshop once Tanmatsu is shipped.

Photos

These photos show some of the prototype 3D printed cases, final design will differ slightly because we are still actively working on improving the design for easier manufacturing and better dust protection.

Special thanks

We want to thank our friends over at YTec 3D for developing the Tanmatsu case and designs. Check out their amazing projects.

Questions?

If you have questions please contact us by joining one of our community chatgroups (Telegram and Discord) or by emailing us.

3 - Tanmatsu: software

Work in progress

The software for Tanmatsu is currently under active development. On this page we will regulary post updates on our progress. Don’t want to miss out on any updates? Join our Discord or Telegram groups.

Device drivers

The invisible though crucial part of all software running on Tanmatsu. These ESP-IDF components provide the building blocks for interfacing with the hardware on the Tanmatsu mainboard.

MIPI DSI display

The Tanmatsu has a MIPI DSI display with a ST7701 controller. Espressif provides a driver for this controller, we added the correct initialization commands and configuration for the display on the Tanmatsu and packaged these in a component. In addition to the configuration of the Tanmatsu display the display included with the Espressif ESP32-P4 devkit is also supported by this component, allowing for easy switching between Tanmatsu hardware and the ESP32-P4 devkit.

Coprocessor

This driver component manages communication with the coprocessor firmware via I2C and exposes functions for accessing all coprocessor functionality.

ES8156 audio DAC

This driver component allows for configuring the ES8156 audio DAC via I2C.

BMI270 IMU

This driver component wraps the Bosch SDK for the BMI270 IMU, implementing communication via I2C for the ESP32-P4.

In circuit programming

These components are as invisible during normal use as they are useful when you need them. To do initial hardware bringup and to update the firmware of the coprocessor and the radio Tanmatsu needs a way to reprogram these chips from the ESP32-P4 application processor.

Tools

The BSP (Board Support Package) wraps the driver components to provide an easy way to integrate board support for Tanmatsu (and other devices) into ESP-IDF projects.

AppFS allows for dynamically installing and running ESP32 firmware from a special flash partition. This mechanism allows for installing and running apps directly from the Tanmatsu launcher.

The LVGL BSP interface is a component providing the glue needed to use the LVGL graphics stack component provided by Espressif with the BSP component, mapping the keyboard buttons and correctly configuring the display and display rotation.

3.1 - AppFS

AppFS is an ESP-IDF component that implements a method for dynamically installing and loading firmware binaries. It implements a pseudo filesystem interface for storing firmwares and a bootloader modification which allows for starting firmwares from the AppFS partition.

Originally AppFS was created by Jeroen Domburg (sprite_tm) for the PocketSprite keychain gameconsole. Since it’s creation Badge.Team has succesfully deployed, updated and extended AppFS to make it the ready to use component it is today.

The current version of AppFS supports ESP-IDF 5.3 and later and has bootloader modifications for the ESP32, ESP32-C6 and ESP32-P4 included. Other ESP32 variants are not supported yet.

Using the AppFS component in your projects

Apps do not require any changes to be started using AppFS, you only need the AppFS component to build a launcher menu.

To include the AppFS component in your launcher menu project first add the component as a requirement using idf.py:

idf.py add-dependency "badgeteam/appfs^1.0.0"

This makes the AppFS APIs available, but does not apply the required bootloader changes.

To apply the bootloader changes either create two symlinks or copy the contents of the folders.

mkdir bootloader_components
ln -s managed_components/badgeteam__appfs bootloader_components/appfs
ln -s managed_components/badgeteam__appfs/bootloader_main bootloader_components/main

The component is now ready for use.

#include "esp_err.h"
#include "esp_log.h"
#include "appfs.h"

void initialize_appfs(void) {
    esp_err_t res = appfsInit(APPFS_PART_TYPE, APPFS_PART_SUBTYPE);
    if (res != ESP_OK) {
        ESP_LOGE(TAG, "Failed to initialize AppFS: %s", esp_err_to_name(res));
        return;
    }
}

See the functions defined in appfs.h for more information on how to use the library.

Partition table

The appfs.h header defines a type and subtype for the AppFS partition:

#define APPFS_PART_TYPE    0x43 /*<! Default partition type of an appfs partition */
#define APPFS_PART_SUBTYPE 0x3  /*<! Default partition subtype of an appfs partition */

To create an AppFS partition add an entry to the partitions CSV file for your project:

# ESP-IDF Partition Table
# Name, Type, SubType, Offset,   Size,
appfs,  0x43, 3,       0x330000, 8000K,

AppFS partition tools

After ESP-IDF has downloaded the component a tools folder can be found at managed_components/badgeteam__appfs/tools. In this folder a set of Python scripts can be found for creating and managing AppFS partition data.

Creating an AppFS partition image

In the partition table above the partition is 8000 KB in size. Converted to bytes 8000 KB becomes 8000 x 1024 = 8192000 bytes.

A partition can be created using the following command:

python appfs_generate.py 8192000 example.bin

To add firmware binaries to the AppFS partition file the appfs_add_file.py tool can be used:

python appfs_add_file.py example.bin myapp.bin "myapp" "My app" 1

The name and title fields are strings. The filename (name field) of the file can be a maximum of 48 bytes long and the title of the file can be 64 bytes long. The version field is an 16 bits unsigned integer with a range of 0 - 65535.

The filename (name field) of the file is used in the AppFS API to identify files in the filesystem, filenames have to be unique. The title field is optional and may be used to include a human readable alternative to the filename. If unused the title field can be set to a blank string "". The version field is also optional and may be used to identify the installed version of an application, allowing for easier implementation of update mechanisms. If unused the version field can be set to 0.

3.2 - BadgeLink

BadgeLink is a protocol for communicating with Tanmatsu over USB. It allows you to manage apps, settings and files on the device via WebUSB applications in Chromium based browsers or a Python script.

Downloading the tools

You can find the Python script on the releases page of the BadgeLink repository. Download the tools.zip artifact and unzip it into a folder.

Make sure Python is installed on your computer.

Installing the tools

A bash shell script has been provided to automatically create a Python virtual environment and install the required libraries into the environment. On Linux and Mac machines you can run this script to automate the process.

On Windows you can manually create the virtual environment by running the following commands in a command window:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Permissions for accessing the USB device on Linux

Copy the 60-badgelink.rules file to /etc/udev/rules.d on your system. Then reload the udev rules and trigger re-detection of hardware.

sudo cp 60-badgelink.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

Running the BadgeLink tool

On Linux and Mac the badgelink.sh script automatically starts the badgelink.py script in the virtual environment. On Windows you have to manually enable the virtual environment as follows:

source .venv/bin/activate
python badgelink.py

Using the BadgeLink tool

Make sure your Tanmatsu is set to USB device mode, by default the USB interface is set to debugging mode and you can change the mode easily by pressing the purple diamond key (second button from the top right of the keyboard). It might take a second before the icon changes but the icon on the top right of the screen will change from the bug to an USB icon to indicate that the USB port mode has been switched.

In the next sections we assume you are using the badgelink.sh script. If you are using Windows replace badgelink.sh in the commands below with python badgelink.py and make sure the virtual envirotnment is active in the command window you are using.

AppFS

Listing installed applications

./badgelink.sh appfs list

This command will list all the application binaries currently installed into the AppFS partition of the flash chip.

Example output:

slug        | title       | version | size 
------------+-------------+---------+------
konsool64   | Konsool 64  | 1       | 833K 
synthwave   | Synthwave   | 1       | 438K 
coprocessor | Coprocessor | 1       | 1063K

In this context slug is a lowercase ascii string without spaces, formatted in such a way to ensure the name can be used as filename. The slug is used for coupling the binary in AppFS with its related files on the FAT partition of flash or the SD card in the /apps/<slug>/ folder. The slug filename needs to be unique for every file in the AppFS.

The title field is a human readable name for the application, this string is visible in the menu and you can safely use uppercase letters and spaces in this string.

The version field contains an integer number used to couple the version of the installed binary in AppFS to the version of its related files on the FAT partition.

The size field contains the size of the application binary in kilobyte.

View partition size and usage

./badgelink.sh appfs usage

This command gives you information on the size of the AppFS partition and the amount of space in use by the installed applications.

Example output:

Usage: 2432K / 8128K (29.9%)

Deleting an application

./badgelink.sh appfs delete synthwave

The last argument in this command is the slug filename of the app you want to remove from AppFS, you can find the slug filename using the list command.

Copying an app from the device to your computer

./badgelink.sh appfs download konsool64 konsool64.bin

This command transfers a file on the AppFS partition to your computer. The last two arguments are the slug filename of the app and the filename of the output file on your computer.

Copying an app from your computer to the device

./badgelink.sh appfs upload test "An example app" 123 firmware.bin

This command transfers a file on your computer to the AppFS partition. The argumens are the slug filename you want the application to have, this name has to be unique, followed by the title of the app, in the example above quotes were added around the string to allow the use of spaces. After that comes the version argument, an integer number, when testing you can use any number you want, for example 0. And the last argument is the filename of the firmware binary you want to upload to the device.

If you have just compiled the example app, take a look in the build folder to find the firmware.bin file. This file is the only file you need for installing your app.

Starting an app

To start an app on the AppFS partition you can use the start command:

./badgelink.sh start synthwave

In which the synthwave argument is the slug name of the app to start.

NVS (Non-volitile storage)

NVS is a partition on the flash which contains a key-value store for settings. Using BadgeLink you can list which keys are in use and read, write and delete the entries.

Listing keys in use

./badgelink.sh nvs list

This command lists all the keys in use. To limit the results to a specific namespace the name of the namespace can be added as an extra argument.

Example output:

namespace | key          | type  
----------+--------------+-------
wifi      | s00.ssid     | string
wifi      | s00.password | string
wifi      | s00.identity | string
wifi      | s00.username | string
wifi      | s00.authmode | u32   
wifi      | s00.phase2   | u32   
system    | ntp          | u8    
system    | timezone     | string
system    | tz           | string
wifi      | s01.ssid     | string
wifi      | s01.password | string
wifi      | s01.identity | string
wifi      | s01.username | string
wifi      | s01.authmode | u32   
wifi      | s01.phase2   | u32

Reading an entry

./badgelink.sh nvs read system timezone string

To read an entry you specify the namespace, key and type of the entry you want to read. The tool then returns you the value.

type: NvsValueString
stringval: "Europe/Amsterdam"

'Europe/Amsterdam'

Writing an entry

./badgelink.sh nvs write test example string "Hello world"

The example command above creates or overwrites an entry in the namespace test, with key example and type string. The value Hello world gets written into the entry.

Deleting an entry

./badgelink.sh nvs delete test example

The example command above deletes the entry example in the namespace test.

FAT filesystem

The internal FAT filesystem partition and the SD card contents can also be manipulated using the BadgeLink tool.

The internal FAT partition on the flash chip is mounted at /int and the SD card is mounted at the path /sd.

Listing the contents of a directory

To list the contents of the root of the internal flash chip filesystem you can run

./badgelink.sh fs list /int

This results in for example the following output:

type | path 
-----+------
dir  | icons

Type can be dir for a directory and file for a file.

File statistics

To query statistics for a specific file you can use the stat command:

./badgelink.sh fs stat /int/icons/menu/wifi_0.png

This gives you information about the size of the file and the timestamps for creation, modification and last access. Note that the timestamps have a high chance of not being accurate. If the timestamp is unavailable you will most likely see 1970-01-01 as the date.

Type:     file
Size:     539
Created:  1970-01-01 01:00:00
Modified: 1980-01-01 00:00:00
Accessed: 1970-01-01 01:00:00

Creating a directory

./badgelink.sh fs mkdir /int/example

Creates a directory called example in the root of the internal flash FAT filesystem.

Removing a directory

./badgelink.sh fs rmdir /int/example

Removes a directory called example from the root of the internal flash FAT filesystem.

Uploading a file from your computer to the device

To send a file to the device you can use the upload command.

echo "Hello world" > example.txt
./badgelink.sh fs upload /int/example.txt example.txt

Downloading a file from the device to your computer

To retrieve a file from the device you can use the download command.

./badgelink.sh fs download /int/example.txt downloaded_file.txt

3.3 - Meshtastic

This document describes how to install Meshtastic compatible firmware onto your Tanmatsu. The Meshtastic firmware for Tanmatsu is in active development and not yet fully stable. You might experience crashes and bugs.

Tanmatsu uses two ESP32 chips, one as application processor and one as radio. The GUI app for Meshtastic, running on the application processor can be installed as an app using BadgeLink. Support for installing applications in a similar fashion on the radio is still being worked on. Because of this it is currently required to replace the radio firmware which provides the launcher and apps on the application processor with WiFi and BLE access when installing Meshtastic onto the radio.

A tool for flashing Meshtastic or the default “ESP-HOSTED” firmware to the radio will soon be provided as a web application making use of Webserial to connect to your Tanmatsu. It is also possible to flash firmware to the radio using esptool.py, the flashing script provided by Espressif. This guide explains how to flash Meshtastic using esptool.py, which is assumed to be installed and available on your system.

Requirements

• Package containing builds of the Meshtastic radio firmware and GUI application
• BadgeLink tools
• Esptool

Download the two archives linked to above and extract them to a folder. Then open a command prompt in that same folder.

Installing the radio firmware

The first step is to replace the ESP-HOSTED radio firmware normally running on the ESP32-C6 with the Meshtastic firmware.

Controlling the state of the radio using the launcher firmware

If the launcher is unable to communicate with the radio via the protocol implemented by ESP-HOSTED the launcher will automatically power off the radio. You can see the state of the radio by looking at the color of the radio LED, which is the middle LED on the left side of the front of Tanmatsu. If the LED is green the radio is powered on and working, if the LED is blue the radio is in bootloader mode and if the LED is off then the radio is powered off.

While on the homescreen of the launcher firmware you can press a key combination to force the radio into either of the three states (off, bootloader and on).

The radio can be flashed using the online recovery tool or using esptool.py via the USB interface exposed by the radio when the radio is in either bootloader or on state. Sometimes the firmware on the radio can cause issues when trying to flash, in such a situation it is useful to try flashing while in bootloader mode. The bootloader is located in read-only memory and will always work, regardless of the state of the installed firmware.

Flashing firmware to the radio using esptool.py

Both the application processor and the radio expose a serial port for debugging and flashing when enabled. The first serial port to appear is the ESP32-P4 application processor and the second serial port is the ESP32-C6 radio.

You can install the Meshtastic firmware by first erasing and then overwriting the firmware on the ESP32-C6 radio using the following commands:

esptool.py --chip esp32c6 erase_flash
esptool.py --chip esp32c6 write_flash 0x0 radio/bootloader.bin 0x10000 radio/firmware.bin 0x8000 radio/partitions.bin

Installing the GUI app

Now that the radio is running Meshtastic the GUI app can be used to interact with the Meshtastic firmware running on the radio.

Switching the USB mode of the ESP32-P4 to BadgeLink mode

Press the purple diamond button while on the homescreen of the launcher firmware. The bug icon in the top right corner of the screen should now be replaced with an USB icon. In BadgeLink mode the application processor exposes an interface which allows for installing applications. You can use this interface using the BadgeLink tools.

Installing the Meshtastic app

Installing the Meshtastic GUI is done using BadgeLink.

Run the following command to install the Meshtastic GUI application:

./badgelink.sh appfs upload meshtastic "Meshtastic" 0 meshtastic-gui.bin