This page contains instructions for flashing new firmware versions onto your device, including how to recover from failed flashes via the desktop companion app.
In general, we recommend that most users update their firmware via the Tangara Companion app. However, there are cases where this may not be possible.
Using the companion CLI
In addition to the graphical companion app, there is a also a lighter weight command-line flashing tool available. Binary releases of this tool can be found in the same 'releases' page on GitHub as the graphical tool.
The source for the CLI can also be found as a crate in the graphical companion's git repository.
Building from source
As the CLI has much lighter weight dependencies, building a version from source is quite straightforward if you already have a rust toolchain available on your system.
$ git clone https://github.com/haileys/tangara-companion.git
$ cd tangara-companion
$ cargo build --package tangara-cli
$ ./target/debug/tangara
tangara-cli 0.4.3
USAGE:
tangara <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
flash
help Prints this message or the help of the given subcommand(s)
Flashing
Once you've obtained a copy of the tangara cli, flashing is very straightforward. Simply plug in your device, ensure the lock switch is in the upper position, and pass the CLI the new firmware file you wish to flash:
$ ./tangara flash ~/Downloads/tangarafw-1.0.1.tra
Manually flashing with esptool
If for some reason the Tangara-specific flashing tools are not viable for you, then you can instead flash new firmware using standard ESP32 tools available from Espressif.
First, you will need to extra the contents of the .tra firmware bundles; these are really just zip files.
$ unzip tangarafw-1.0.1.tra
Archive: tangarafw-1.0.1.tra
inflating: tangaraflash.json
inflating: tangara.bin
inflating: lua.bin
(If you're not comfortable with command-line tools, you can also just rename the .tra file to a .zip file and use a graphical extraction tool.)
Next, you will need to consult the tangaraflash.json manifest to check where the included binary images should be flashed:
$ cat tangaraflash.json
{
"version": 0,
"data": {
"firmware": {
"version": "1.0.1",
"images": [
{ "addr": 65536, "name": "tangara.bin" },
{ "addr": 11599872, "name": "lua.bin" }
]
}
}
}
(Again, if you're not comfortable with the command line then a program like Notepad will open tangaraflash.json just fine.)
In this example, tangara.bin should be flashed at address 65536, and lua.bin should be flashed at address 11599872.
Using a web tool
There are several web versions of esptool available, which allow you to flash ESP devices from Chrome-based web browsers. These instructions are written with Espressif esptool.js in mind.
First ensure that your Tangara is plugged in, with the lock switch in the upper position. Then, in the Program section of the page, click 'Connect'.
From the dialog that appears, select your device. It should be called something like 'Tangara'.
Then, configure the flash addresses and files according to the information from tangaraflash.json:
Wait for the console output to finish, then click 'Disconnect'. Your device is now flashed, but still need to be properly rebooted.
In the Console section of the page, click 'Connect'.
Select your Tangara from the list that appears, as before.
In the new page that appears, first click Reset (it will seem like nothing happened), then click Stop.
Your Tangara should now boot up into the newly flashed firmware.
Using esptool.py
Using esptool.py, we can flash all images and reboot the device from a single invocation:
esptool.py --port /dev/serial/by-id/usb-cool_tech_zone_Tangara_* write_flash 65536 tangara.bin 11599872 lua.bin
Note that the --port argument may vary on your system. In some cases, you may be able to omit this argument completely and rely on esptool to detect the correct serial port to use.