Talking to the Frame Over Bluetooth

You may want to communicate with the Frame manually over Bluetooth Low Energy if we don’t yet have an SDK available for your preferred development language, or if you just want to understand what’s going on under the hood.

Once you’re communicating with the Frame over Bluetooth, you can use the Lua API Reference to see everything you can tell it to do.

Table of Contents

  1. Pairing & Connecting
  2. Bluetooth Service & Characteristics
  3. Executing Lua Over Bluetooth
  4. Sending Data
  5. Control Characters
  6. Firmware Updates

Pairing & Connecting

Frame uses BLE bonding and must pair with a host device before any communication can take place. When attempting to connect to the Frame using an SDK, the Frame will automatically initiate pairing, which the OS handles and the user will have to agree to.

Full Bluetooth Connection Details

Un-Pairing

Bluetooth Connection Technical Diagram

Bluetooth connection sequence diagram

Bluetooth Service & Characteristics

Frame has a single BLE service containing two characteristics. One for transmitting and one for receiving data.

Lua strings can be sent on the TX characteristic as UTF-8 strings, and responses are returned back on the RX characteristic. The host device must enable notification on the RX characteristic in order to receive data.

  • Service UUID: 7A230001-5475-A6A4-654C-8431F6AD49C4
  • RX characteristic UUID: 7A230002-5475-A6A4-654C-8431F6AD49C4
  • TX characteristic UUID: 7A230003-5475-A6A4-654C-8431F6AD49C4

Executing Lua Over Bluetooth

You can run Lua commands on the Frame over Bluetooth using a REPL-like interaction. Frame does not contain a complete Lua REPL, but rather evaluates every message and only returns a message if it resulted in the Lua print() function being called, or an error.

print('hello world') -- Returns 'hello world' on the RX characteristic
print(1 + 2) -- Returns 3
a = 1 + 2 -- Evaluates 1 + 2 and stores it in a, but does not return anything
1 + 2 -- Returns an error because 1 + 2 hasn't been assigned to anything

Sending Data

Sometimes it may be more efficient to send raw byte data rather than strings. For example when transmitting graphical or microphone data. These can be sent on the same TX characteristic by simply prepending a byte of value 1 at the start of the payload.

Control Characters

While a Lua script is running, Frame will ignore any other Lua strings that are sent over Bluetooth. To interrupt a running script, the following control signals can be sent:

  • Sending a single byte of value 3 will terminate any running script or loop.
  • Sending a single byte of value 4 will clear all variables, and run main.lua if it exists. Same as a reboot.

Firmware Updates

Frame contains a mechanism for updating the complete system firmware via a built in bootloader. To enter the bootloader, call frame.update(). The device will then reboot and advertise with the name “Frame update”.

The latest release file of the official firmware is available from the Frame codebase releases page.