OpenBttn is a custom open source firmware for bt.tn buttons. This firmware does not communicate with the official bt.tn servers and contains some features not available in the original firmware. It's written using the libopencm3 firmware library for ARM Cortex-M3 microcontrollers.
This firmware is in no way associated with The Button Corporation Ltd.
Installing this firmware will most likely void your warranty.
Herein, bt.tn refers to The Button Corporation Ltd., and bttn refers to a consumer device manufactured by said company.
Similar to stock firmware, OpenBttn supports:
- Single and long press button actions
- LED response to button presses
Plus:
- Low latency response times - no bt.tn server registration
- Wi-Fi SSIDs may contain spaces and other special characters
- Live configuration via bttn's web interface
- Built-in socket server provides API commands including custom LED flashing
- OTA update of the SPWF01SA Wi-Fi module
- Password authentication for bttn configuration
The following bttn models have been tested and confirmed working:
- bttn Wi-Fi
- bttn Mobile Data
- bttn Mini Wi-Fi
- bttn Mini Mobile Data
- Download the latest release or build the project yourself
- (Optionally) backup the existing firmware
- Install new firmware
- (Optionally) update the Wi-Fi module firmware
- Boot bttn in recovery mode to input your Wi-Fi settings
- Reboot your bttn
- Live configure the button press URLs using Web-UI
- Enjoy your OpenBttn!
You may compile the firmware yourself or use a pre-compiled firmware image.
Grab the newest release and unzip it.
Install the GNU ARM Embedded Toolchain:
$ brew cask install gcc-arm-embeddedCheck out and build the project:
$ git clone https://github.com/mafredri/openbttn && cd openbttn
$ git submodule update --init
$ make # builds src/main.elf
$ cd src && make bin # builds src/main.binThis firmware can be installed in two ways, either via DFU mode or via the JTAG interface on the bttn board.
Only DFU mode is covered here.
- Open the bttn by removing the three T10 torx screws
at the bottom. - Connect the Boot pins on the board (note: only the Boot pins, not the FWSel ones). An easy way to do this is with a paper clip and a bit of electrical tape twice-folded so as to insulate the paper clip so that it does not touch the FWSel pins or any other contacts on the board.
- Connect the bttn via USB to computer
- Run via terminal:
$ dfu-util --listYou should see output like the following. Note that the device ID (product and vendor) will likely be the same if you're using a Wi-Fi bttn (0483:df11). This may vary with other bttn models (untested).
Found Runtime: [05ac:8290] ver=0146, devnum=5, cfg=1, intf=5, path="20-3", alt=0, name="UNKNOWN", serial="UNKNOWN"
Found DFU: [0483:df11] ver=2200, devnum=28, cfg=1, intf=0, path="20-1", alt=2, name="@DATA Memory /0x08080000/02*004Ke", serial="76B0A1336969"
Found DFU: [0483:df11] ver=2200, devnum=28, cfg=1, intf=0, path="20-1", alt=1, name="@Option Bytes /0x1FF80000/01*032 e", serial="76B0A1336969"
Found DFU: [0483:df11] ver=2200, devnum=28, cfg=1, intf=0, path="20-1", alt=0, name="@Internal Flash /0x08000000/1024*256 g", serial="76B0A1336969"
The device ID shown here is 0483:df11.
If your output looks like the above, you are ready to proceed.
To back-up the firmware from the device, we will tell dfu-util to upload it to us. Use the device ID from the output of running dfu-util --list above.
$ dfu-util --device 0483:df11 --dfuse-address 0x08000000 --alt 0 --upload backup.binThis will upload the firmware from the bttn to your computer and save it as backup.bin. You may later use this backup to restore your bttn to its original state.
If you compiled the firmware yourself (above), you can now flash it to your Wi-Fi bttn:
$ cd openbttn/src && make downloadmake download has the same effect as manually issuing a dfu-util download command and requires a Wi-Fi bttn to be connected and the image built from source available as src/main.bin.
To install new firmware onto the bttn, we will tell dfu-util to download it to the device. Use the device ID from dfu-util --list above.
In the example below, a release image named openbttn-v1.0.1.bin has been downloaded.
Flash the bttn with the image:
$ dfu-util --device 0483:df11 --dfuse-address 0x08000000 --alt 0 --download openbttn-v1.0.1.binYou will see output like the following as the original firmware is overwritten:
dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuERROR, status = 10
dfuERROR, clearing status
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash "
dfu-util: Non-valid multiplier ' ', assuming bytes
Downloading to address = 0x08000000, size = 23288
Download [=========================] 100% 23288 bytes
Download done.
File downloaded successfully
- Unplug the device from power
- Remove the jumper/short of the boot pins
- (Optionally) reassemble the unit
Plug in the bttn while holding down the button. After 4 seconds it will enter recovery mode and start an open Wi-Fi access point.
- Next, connect your computer to the
OpenBttnWi-Fi network. - Open a browser to http://192.168.1.1/
- Configure the bttn to use your network's Wi-Fi settings.
You will not need to re-enter recovery mode unless your Wi-Fi network settings have changed.
Use a web browser to connect directly to your bttn once it's on your network. You must know your bttn's IP address which you can find out from your router or DHCP server.
Navigate to http://[bttn_IP_on_your_network]/ and set your short and long-press URLs.
You may reconfigure your bttn as often as desired.
There are several functions available via the socket server. Note that URLs must be encoded to AT format before being passed to the socket server. Refer to at.js for more information.
dump_config- return current configurationblink_leds- change LED colors in a sequenceurl1- set short-press URLurl2- set long-press URLpassword- set management password
Set a shell variable for the socket server's URL:
$ export BTTNSOCK="http://[bttn_IP_on_your_network]:8774/socket"Read configuration for button press actions:
$ curl -w "\n" --data $'auth = PASSWORD\r\ndump_config' $BTTNSOCKExample output (JSON):
{"url1":"10.1.5.13,/shortPress,4040","url2":"10.1.5.13,/longPress,4040"}
Turn on the LEDs (white) for 400ms and then them off:
$ curl -w "\n" --data $'auth = PASSWORD\r\nblink_leds = ffffff;400;0;0' $BTTNSOCKExample output (plaintext):
Success!
OpenBttn contains a development server written in Go, it can be used for developing the web UI locally or for serving the OTA update for the SPWF01SA module.
Installation via macOS:
$ brew install goUsage:
$ go run cmd/openbttn/main.go -ip 192.168.0.123 -ota ./public/ota -public ./public/openbttn-ip assumes button is at IP 192.168.0.123, used for redirecting some communication while developing the Web UI.
-ota path to folder containing Wi-Fi module OTA image (more on this below)
-public path to folder containing Web UI.
The development server serves everything at http://localhost:8774.
Depending on when your bttn was built, it may have shipped with an older Wi-Fi module firmware. It's recommended to upgrade this firmware, and the process is stable and safe, but as with all things, your mileage may vary.
As of this writing, version 3.5.3 is available and brings many improvements over older versions.
Download the latest Wi-Fi module firmware from here (requires signing up for a free account).
Unzip it and locate the module firmware version you wish to use.
For our example, we've chosen:
SPWF01S-170111-665d284-RELEASE-main.ota
Move the firmware into the ota folder:
$ mv ~/Downloads/STSW-WIFI001/Rel.\ 3.5.3/OTA/SPWF01S-170111-665d284-RELEASE-main.ota public/ota/Run the included web server (more on this in Development server):
$ cd public && go run ../cmd/openbttn/main.goBoot bttn in recovery mode and join the OpenBttn Wi-Fi network.
Next, navigate to http://192.168.1.1 and verify that the update URL shown matches what you expect, and that you can reach that URL yourself (doing so should trigger a file download).
If it's working as expected, you may update the Wi-Fi module firmware. After the update has succeeded, you may need to reconnect to the OpenBttn Wi-Fi access point to proceed with (re)configuring the Wi-Fi settings.
- Document how LEDs can be specified or individually addressed in
blink_ledscommand
- OTA update of OpenBttn (we are already able to OTA update the Wi-Fi module, updating OpenBttn remotely would also be nice)
- More ways to interact with the bttn (double press, ulta-long press, etc?)
- We cannot use hardware flow control for the SPWF01SA Wi-Fi module because the CTS/RTS ports of the Wi-Fi module are incorrectly set up in the bttn hardware. The CTS/RTS is set up as output/input whereas is should be the other way around, input/output. This makes it impossible for the bttn (RTS) to send signals to the Wi-Fi module (CTS) and vice-versa.
- Using hardware flow control would allow us to use a smaller ring buffer and ask the WiFi module to take breaks in sending it's data, thus relying on it's, much larger, RAM.
- I happened to have a bricked (after OTA update) bttn around to play with and wanted some experience with embedded programming
- Local requests in original firmware were too slow
- A token request to the bt.tn servers were issued before the local request was performed
- Investigate Wi-Fi issues in bttn
- Turns out it's an issue with the SPWF01SA Wi-Fi module
- Can be worked around by running the WiFi module in power save mode or by connecting to a different WiFi AP