MicroPython lets you prototype and build your applications quickly without having to dive into any low level programming. With a few lines of Python, you can draw to the display, access the camera, and offload processing to the FPGA. Of course you get all the other benefits of Python too. Best of all, it’s completely wireless, and you can access the Python REPL fully over Bluetooth.
The MicroPython firmware for Monocle is a customized firmware which is largely based on the upstream MicroPython project. Thanks to the large MicroPython community, we’re always updating to new features as they come out on the upstream project.
A subset of the standard MicroPython libraries are currently supported, with more periodically being added. Additionally, some extra modules are included which let you easily interact with the Monocle hardware. Be sure to check out the MicroPython docs site, as well as the docs here to familiarize yourself with all the features.
Check that you’re on the latest firmware.
Once you’re connected, try running this code:
import touch import display fn change_text(): display.fill(0) display.text("touched!", 0, 0, 0xffffff) display.show() touch.bind(touch.A, touch.TAP, change_text) display.fill(0) display.text("tap touch A", 0, 0, 0xffffff) display.show
We’re gradually building our companion app along with some extra features to help you get the most out of Monocle. It’s also a great place to start if you’d like to make your own app, and the source code is freely available on our GitHub.
MicroPython for Monocle is always being updated so be sure to check back frequently. The ❌ icon signifies a feature which is not implemented yet, but is planned.
device– Monocle specific
display– Monocle specific
camera– Monocle specific
microphone– Monocle specific
touch– Monocle specific
led– Monocle specific
fpga– Monocle specific
storage- Monocle specific
bluetooth- Monocle specific
time– Monocle specific
The majority of built in functions are supported, along with some extended features below. Some less important features are not included to save on space for other things. If you feel we’ve missed something, create an issue on our GitHub, and we’ll try to add it.
|Byte arrays are supported.|
|Dictionaries are supported.|
|Enumerate loops are supported.|
|Floating point numbers are supported.|
|The max function is supported.|
|The min function is supported.|
|Reversing lists are supported.|
|Sets are supported.|
|Slices are supported.|
|Unicode and string handling is supported.|
The device class contains general information about the Monocle’s hardware and firmware.
|Constant which holds |
|Returns the 48-bit MAC address as a 17 character string in the format |
|Constant containing the firmware version as a string. E.g. |
|Constant containing the build git tag as a 7 character string.|
|Returns the battery level percentage as an integer.|
|Resets the device.|
|Returns the reason for the previous reset or startup state. These can be either:|
The display module allows for drawing to the micro OLED display. An image can be prepared using the functions below, and then
show()can be used to print the image to the display.
|Fills the entire display with a color. |
|Draws a single pixel of color |
|Draws a horizontal line from the position |
|Draws a vertical line from the position |
|Draws a straight line from the position |
|Draws text at the position |
|Prints the populated frame buffer to the display. After this call, another series of drawing functions may be called and |
|Powers up the display if |
|Equal to |
|Equal to |
The camera module allows for capturing images and transferring them to another device over Bluetooth.
|Captures an image and returns it to a device over Bluetooth. See downloading media to understand how media transfers are done.|
|Powers up the camera if |
|Equal to |
|Equal to |
The microphone module allows for capturing audio and streaming it to another device over Bluetooth.
|Streams audio from the microphone to a device over Bluetooth. See downloading media to understand how media transfers are performed.|
The touch module allows for reacting to touch events from the capacitive touch pads on Monocle.
|Attaches a touch action (either |
|Returns the current touch state of the pad |
|Enumeration which represents Pad A.|
|Enumeration which represents Pad B.|
|Enumeration which represents a single tap action.|
|Enumeration which represents a double tap action.|
|Enumeration which represents a long press or hold of 1 second.|
|Enumeration which represents a slide action from A to B, or B to A. the |
The LED module contains functions to control the red and green LED on the front of Monocle.
|Illuminates an led. |
|Turns off an led. |
|Enumeration of the red led which can be passed to |
|Enumeration of the green led which can be passed to |
The FPGA module allows for direct control of the FPGA, as well as the ability to update the bitstream.
|Writes all bytes from a given bytes object |
|Powers up the FPGA if |
|Downloads and reboots the FPGA with a bitstream provided from the |
|Returns the current status of the FPGA:|
|Equal to |
|Equal to |
Storage can be used for reading or writing to files within the non-volatile storage.
"file"can be any user defined string, however certain strings are reserved for special uses such as
"fpga-bitstream"which is used to store the FPGA application.
|Reads and returns a bytes object from a file within the non-volatile storage. |
|Creates a new file with name |
|Appends data from a bytes object |
|Deletes a file from the storage.|
|Lists all files currently on the device.|
|A special filename which is used for storing the FPGA bitstream. This file can not be deleted, and must be populated for the FPGA to start up.|
bluetoothmodule can be used to transfer byte data between Monocle and the host Bluetooth device. Bytes can contain any arbitrary data, and avoids having to pollute the REPL interface with printing data out as strings. The raw data service is used for all communications under the
|Sends data from a bytes object |
|Receives data over the raw data service and returns a bytes object.|
|Returns the maximum negotiated payload size for Bluetooth transfers.|
The time module allows for getting/setting the time and date as well as adding delays into your programs.
|Sets or gets the current system time in seconds. If |
|Sets or gets the time zone offset from GMT as a string. If |
|Returns a dictionary containing a human readable date and time. If no argument is provided, the current system time is used. If |
|The inverse of |
|Sleep for a given number of seconds.|
|Sleep for a given number of milliseconds.|
|Returns a timestamp in milliseconds since power on.|
Standard MicroPython garbage collection is supported.
Standard MicroPython math functions are supported.
Standard MicroPython internals are supported.
Standard MicroPython asynchronous scheduling is supported.
Standard MicroPython binary/ASCII conversions are supported.
Standard MicroPython system error codes are supported.
Standard MicroPython IO streams except for
Standard MicroPython JSON handling is supported.
Standard MicroPython random number generation is supported.
Standard MicroPython regular expressions are supported.
This section describes how data is transferred to and from Monocle over Bluetooth.
All MicroPython communication, i.e. the REPL interface, is accessed via a single Bluetooth Service containing two Characteristics.
- Serial service UUID: 6e400001-b5a3-f393-e0a9-e50e24dcca9e
- Serial RX characteristic UUID: 6e400002-b5a3-f393-e0a9-e50e24dcca9e
- Serial TX characteristic UUID: 6e400003-b5a3-f393-e0a9-e50e24dcca9e
The RX characteristic is write only, and transports serial string data from the central BLE device to Monocle. The TX characteristic is notification only and delivers messages back from Monocle, to the central BLE device.
Each characteristic transports string data of any length up to the negotiated MTU size - 3 bytes. Longer strings must be chopped up and will be automatically rejoined on the receiving side by Monocle. Likewise if Monocle wishes to send longer responses than can fit into a single MTU payload, the data will arrive sequentially, and can be concatenated by the central Bluetooth app. The diagram below describes how communication operates between Monocle and a central device.
A secondary Bluetooth Service, again containing two Characteristics, is used to transport raw data such as image, audio and firmware update data. The mechanism for the raw data service is similar to the serial data service, aside from the fact that
0 characters may also be included within the payload.
- Raw data service UUID: e5700001-7bac-429a-b4ce-57ff900f479d
- Raw data RX Characteristic UUID: e5700002-7bac-429a-b4ce-57ff900f479d
- Raw data TX Characteristic UUID: e5700003-7bac-429a-b4ce-57ff900f479d
Raw data transfer may often be bigger than a single MTU payload. Similarly to the serial data, it may need to be broken up into pieces. To help reconstruct the packets sent or received by Monocle, a flag is present at the start of each payload to determine if it’s either a starting payload, middle payload, end payload, or a small single buffer payload. The exact mechanisms for different types of data transfer are outlined below.
Media files such as audio and images may be downloaded from the Monocle using the raw data service mentioned in the Communication section. Files may also be sent asynchronously by Monocle when they are ready.
Due to the small payload size of Bluetooth packets, the file may be spit into many chunks and need to be recombined by the receiving central device. A flag at the start of each payload indicates if it is the START, MIDDLE or END of the file. A very small file may also be transferred using the SMALL flag.
The first payload includes metadata about the file such as the filename (with a relevant file extension) and the file size. The sequence diagram below describes how a file is broken into several parts and the data can be recombined to construct the full file:
Updates of the MicroPython firmware are handled using Nordic’s over-the-air device firmware update process.
To perform an update:
Check which version of the firmware you current have by entering
import device; device.VERSION.
Download the latest
monocle-vXX.XXX.XXXX.zippackage from our GitHub releases page.
Issue an update command over MicroPython using
import device; device.update(). Monocle will now reboot into DFU mode.
Details coming soon.