search

usetrmnl / firmware

TRMNL device firmware
https://docs.usetrmnl.com
GNU General Public License v3.0
33 stars 5 forks source link
e-ink iot-device

readme

TRMNL Firmware

created for the TRMNL e-ink display.

Algorithm block scheme

Image Alt text

Web Server Endpoints

following Wifi connection via the captive portal, device swaps its Mac Address for an API Key and Friendly ID from the server (which get saved on device).

GET /api/setup

headers = {
  'ID' => 'XX:XX:XX:XX:XX' # mac adddress
}

response example (success):
{ "status": 200, "api_key": "2r--SahjsAKCFksVcped2Q", "friendly_id": "917F0B", "image_url": "https://usetrmnl.com/images/setup/setup-logo.bmp", "image_name": "empty_state" }

response example (fail, device with this Mac Address not found)
{ "status" => 404, "api_key" => nil, "friendly_id" => nil, "image_url" => nil, "image_name" => nil }

assuming the Setup endpoint responded successfully, future requests are made solely for image / display content:

GET /api/display

headers = {
  'ID' => 'XX:XX:XX:XX',
  'Access-Token' => '2r--SahjsAKCFksVcped2Q',
  'Refresh-Rate' => '1800',
  'Battery-Voltage' => '4.1',
  'FW-Version' => '2.1.3',
  'RSSI' => '-69'
}

response example (success, device found with this access token):
{
  "status"=>0, # will be 202 if no user_id is attached to device
  "image_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.bmp",
  "image_name"=>"2024-09-20T00:00:00",
  "update_firmware"=>false,
  "firmware_url"=>nil,
  "refresh_rate"=>"1800",
  "reset_firmware"=>false
}

response example (success, device found AND needs soft reset):
{
 "status"=>0,
 "image_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.bmp",
 "image_name"=>"name-of-img.bmp",
 "update_firmware"=>false,
 "firmware_url"=>nil,
 "refresh_rate"=>"1800",
 "reset_firmware"=>true
}

response example (success, device found AND needs firmware update):
{
 "status"=>0,
 "image_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.bmp",
 "image_name"=>"name-of-img.bmp",
 "update_firmware"=>true,
 "firmware_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-firmware.bin",
 "refresh_rate"=>"1800",
 "reset_firmware"=>false
}

response example (fail, device not found for this access token):
{"status"=>500, "error"=>"Device not found"}

if 'FW-Version' header != web server `Setting.firmware_download_url`, server will include absolute URL from which to download firmware.

if device detects an issue with response data from the api/display endpoint, logs are sent to server.

POST /api/logs

# example request tbd

Power consumption

Ths image displays the amount of power consumed during a work cycle that involves downloading and displaying images.

Image Alt text

This image displays the amount of power consumed while in sleep mode.

Image Alt text

This image displays the amount of power consumed during a work cycle that involves link pinging, new firmware downloading and OTA.

Image Alt text

Full Power Cycle

If refreshed continuously, device will refresh 8,231 times (54 hours) on a full charge. If device is set to sleep continuously, it can sleep for 18,000 hours (750 days).

15 min refresh = 78 days 5 min refresh = 29 days

Low Battery Level

This image shows that the battery disconnects when the voltage reaches 2.75 V:

Image Alt text

The pulse on the graph shows the voltage on the divider in sleep mode, further on the graph it can be seen that at the moment of disconnection of the battery on the divider under load the voltage is equal to 1V, i.e. a voltage of 1.2V under load on the divider can be considered extremely critical, which corresponds to a voltage of 1.5V in the state sleep on the divider and 3V on the battery:

Image Alt text

Version Log

[v.1.0.0]

[v.1.0.1]

[v.1.0.2]

[v.1.0.3]

[v.1.0.4]

[v.1.0.5]

[v.1.0.6]

[v.1.0.7]

[v.1.0.8]

[v.1.0.9]

[v.1.1.0]

[v.1.2.0]

[v.1.2.1]

[v.1.2.2]

[v.1.2.3]

[v.1.2.4]

[v.1.2.5]

[v.1.2.6]

[v.1.2.7]

[v.1.2.8]

[v.1.2.9]

[v.1.2.10]

[v.1.2.11]

[v.1.2.12]

[v.1.2.13]

[v.1.2.14]

[v.1.2.15]

[v.1.2.16]

[v.1.2.17]

[v.1.2.18]

[v.1.3.0]

[v.1.3.1]

[v.1.3.2]

[v.1.3.3]

[v.1.3.4]

[v.1.3.5]

[v.1.3.6]

[v.1.3.7]

Compilation guide

  1. Install the VScode https://code.visualstudio.com
  2. Install PlatformIO https://platformio.org/install/ide?install=vscode
  3. Install Git https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Visual-Studio-Code
  4. Clone repository from github https://github.com/usetrmnl/firmware
  5. After cloning “Open” project in workspace
  6. After configuring the project, click on the PlatformIO -> Build button located at the bottom of the screen

Image Alt text

  1. After the compilation process is complete, you should expect to see a message in the console.

Image Alt text

  1. You can find the compiled file in the folder shown in the picture

Image Alt text

Uploading guide (PlatformIO)

  1. Connect PCB to PC using USB cable.

  2. Select the proper COM port from drop-down list

Image Alt text

  1. Click on "PlatformIO: Upload" button

[!WARNING]

If the board does not want to be flashed, then try to enter the flashing mode manually. To do this, turn off the board using the switch, hold the button and turn on the board. After it you can try to upload firmware again

Uploading guide (ESP32 Flash Download Tool)

Tools required:

  1. Windows OS
  2. Flash Tool 3.9.5
  3. Firmware binary file
  4. Bootloader binary file
  5. Partition binary file
  6. Boot app binary file

Step 1 - Configure flash tool

open the Flash Tool (executable file), select these parameters, then clickOK:

Image Alt text

Step 2 - Add binaries

  1. Beside the top blank space, click “...” dots and select the bootloader binary file then input

    “0x00000000” in the far right space and check the box.

  2. Click “...” dots and select the partitions binary file then input

    “0x00008000” in the far right space and check the box.

  3. Click “...” dots and select the boot_app0 binary file then input

    “0x0000e000” in the far right space and check the box.

  4. Click “...” dots and select the firmware binary file then input

    “0x00010000” in the far right space and check the box.

Image Alt text

finally, set the following parameters at the bottom of the Flash Tool interface:

Image Alt text

Step 3 - Connect and flash device

  1. Open the Windows “Device Manager” program and scroll to the bottom where the USB devices can be found. each machine will have different available devices, but look for a section like this:

Image Alt text

  1. Next, connect the PCB to the Windows machine with a USB-C cable. make sure the USB port is on the right, and that the PCB’s on/off switch is toggled DOWN for “off.”

  2. While holding the BOOT button (below the on/off toggle), toggle the device ON by flipping the above switch UP. you may hear a sound from your Windows machine Inspect the Device Manager connections at the bottom of the interface, and a new device should appear. it may be “USB Component {{ Num }},” or something like below:

Image Alt text

  1. Take note of this device’s name, that is our TRMNL PCB. then back inside the Flash Tool, click to open the “COM” dropdown in the bottom right and choose the TRMNL PCB. finally, click the “START” button.

Image Alt text

Step 4 - Setup device by Mac Address

The Flash Tool will quickly add the firmware to the TRMNL PCB, and you need to copy the “STA” value from the info panel. this is the device Mac Address:

Image Alt text

In this example, the device’s Mac Address is:

DC:DA:0C:C5:7E:4C

This Mac Address should be provided to the TRMNL web application admin panel > Devices > New Device to instantiate this device to be ‘claimed’ by a customer later, when they unbox the product.

Image Alt text

Step 5 - Prepare for new device flashing

Inside the Flash Tool click the “STOP” button.

Image Alt text

Next turn off (toggle DOWN) and unplug the PCB. you are now ready to flash another device - see Step 1.