/filters:background_color(white)/2024-03/canvas-software-suite-red.png)
/filters:background_color(white)/2024-03/Family%20-%20Sera%20NX040%20-%20Embossed%20-%20nxp-nordic.png)
Introduction
The Sera NX040 module is supported by Canvas Platform Firmware as part of the Canvas Software Suite. This firmware provides developers a path to quickly design and build applications using the Python language and leverage Python-based APIs for access to the underlying hardware and radio feature set. This guide focuses on developing software for the Sera NX040 DVK, though the principles described apply to any PCB on which the Sera NX040 module is placed as long as the appropriate SWD and serial port access is provided by the PCB to use with Canvas Tools for programming.
Getting Started
The Sera NX040 DVK is equipped with a USB port (silk screen label DEBUG) used to both provide access to SWD programming capabilities and access to two USB-to-UART interfaces to the Sera NX040 module. This is the primary interface you will use when developing software for the Sera NX040 module.
This USB port connects to an on-board RP2040 MCU programmed with DAPLink compatible firmware to provide the programming interface to the module.
When you plug a micro-USB cable from the DEBUG USB port into your workstation, the DVK hardware will be auto-detected and drivers are installed for the two serial ports. One serial port will provide access to the Zephyr RTOS shell (uart:~$) and the other to the Python REPL prompt (>>>). You can attach to each serial port with 115200 baud, 8N1 to verify your DVK is running Canvas Firmware.
If you do not see this output, you can press the RESET button (SW1, labeled NX040 RST on the DVK silk screen) to reset the firmware and something similar to the output above will appear in a serial terminal.
If you do not see any output similar to above, you may need to load Canvas Firmware onto your DVK board. To do so, follow the steps in the next section to update your Canvas Firmware.
Updating Canvas Firmware
Downloading the Latest Firmware Image
The latest version of Canvas Firmware for the Sera NX040 module can be found here:
https://github.com/LairdCP/Sera_NX040_Firmware/releases
Download the latest version of the .zip file (name starting with Sera-NX040-Firmware_480-00336). It contains a .hex file starting with 480-00336 and ending in full-image.hex.
Programming the Firmware onto the DVK
Programming firmware onto the Sera NX040 DVK depends on pyocd which requires Python to be installed on your workstation. We recommend installing Python v3.11.6 on your workstation for best compatibility with Canvas Tools. Note that Python v3.12 does not work properly with pyOCD and Canvas Tools as of the writing of this document.
Using pyocd From the Command Line
With Python 3.11.6 installed, you can find more details on how to install and use pyocd here: https://pyocd.io/docs/installing . Once pyocd is installed, you can use it from a command line to program the DVK board as follows:
pyocd flash -t nrf52833 -e chip 480-00336-R1.0.0.1697218537_full-image.hexUsing the Canvas Xbit Extension for VS Code
With Python 3.11.6 installed, you also have the option of using our Xbit VS Code extension to load .hex files right from within the VS Code editor environment.
Install the Xbit tools for VS Code extension by navigating to the Extensions tab
within VS Code and searching for “Xbit tools for VS Code”.
To load a .hex file from the Xbit VS Code extension (Xbit VSC), make sure your board is connected to your workstation via the DEBUG USB port and navigate to the Xbit VS Code panel on the sidebar.
This will display a file selection dialog where you can select the Sera NX040 firmware .hex file you downloaded from the release page and program it to the DVK board. In the background the Xbit VS Code extension uses pyocd to perform the programming. Programming can take up to a minute, so please be patient and let the process finish before proceeding.
Interacting with the Sera NX040 DVK via Python REPL
The Canvas Firmware provides a Python execution environment right on the Sera NX040 module. This environment can be interacted with through the Python REPL serial port. The Xbit VS Code extension will automatically detect this serial port and provide easy access to the REPL terminal.
To access the Python REPL, ensure your DVK’s USB DEBUG port is attached to your workstation and open the Xbit VS Code extension. Navigate to the USB DEVICES panel and locate the serial port associated with your DVK board. Click the board name (e.g. ‘Sera NX040 DVK COM26' or similar) to connect to the board and expand a listing of its filesystem. In the lower right, you’ll find a tab labeled TERMINAL. If you press the ENTER key in the TERMINAL panel, you’ll see the REPL prompt for the device (>>>). From here, you can type Python commands interactively with the DVK board.
One common set of commands provides an easy way to find the Canvas Firmware version running on your device. Type the following lines, pressing ENTER after each one into the REPL terminal to display the system version information. The Canvas Firmware version is the string value for the property named release.
>>> import os
>>> os.uname()If the commands were issued properly, you should see a Python tuple displayed similar to the following:
(sysname='zephyr', nodename='zephyr', release='1.0.0+1697218537',
version='v1.20.0-484-g5473200aa on 2023-09-22', machine='sera_nx040_dvk')Creating a Python File
The Python interpreter built into the Canvas Firmware running on the Sera NX040 DVK is designed to look for two specially named Python files in its filesystem at system boot. These files are named boot.py and main.py. If a file named boot.py exists in the filesystem, the Python code in that file will be executed automatically on boot, allowing you to easily configure the hardware for your preferred startup conditions. After executing the boot.py script, the interpreter looks for a main.py and if it exists, executes it. This allows you to automatically launch a Python script application after system boot.
To create a Python file on the device, right-click the device name in the USB DEVICES panel in the Xbit VS Code extension and select Create File. This will bring up a field where you can specify the name of the file (e.g., ‘main.py’).
The new file will now appear in the file listing under the device in the USB DEVICES panel. To edit the file, click on the file in the panel and a new editor tab will display. You can now type in this editor and save using FILE → SAVE or the hotkey for saving a file on your platform to save the updated file back to the device. To edit a file already on the device, just click the name of the file and an editor tab will open where you can modify and save the file like you usually would any text file within VS Code.
Next Steps
Now that you have your DVK connected to your workstation and have the Xbit VS Code extension up and running and interacting with the board, you are ready to try out some sample Python applications or develop your own. Note that sample applications may not be named main.py, in which case in order for the script to run on startup, simply rename the script to main.py before loading to the board or use the Right-click context menu within Xbit VS Code extension to rename the file to main.py in order for the device to automatically run the script after a reset.
Python Sample Applications
We’ve provided a set of simple Python applications for you to get started with some simple examples and test out the hardware. These samples are hosted in a public GitHub repository and will evolve over time to include more examples of exciting things you can do with Python on the Canvas Firmware with your DVK board. Please check this GitHub repository for a list of sample applications:https://github.com/LairdCP/canvas_python_samples
NOTE: Not all sample applications work properly with all Canvas Firmware supported hardware. Please take note of the requirements described in each sample application to ensure it is compatible with your hardware. The Canvas API Compatibility Table is a useful resource for determining which Python APIs are available on each Canvas-enabled hardware product.
Python API Documentation
Once you’ve taken a look at some sample applications and start to become familiar with how Python can be used to develop applications on the device, you can check out our detailed Python API documentation for more details on what hardware is accessible from Python and how to use it.
Canvas Python API Documentation on GitHub
Canvas API Compatibility Table - Sera NX040
The following table lists the specific Python APIs available on the Sera NX040 module.
Python API Compatibility | ||||||||||||||
machine. | machine. | machine. | canvas_ble. | canvas_ble. | canvas_ble. | canvas_ble. | canvas_ble. | canvas. | canvas_ble | canvas_uwb | Floating | canvas. | canvas. | |
Sera NX040 |  | | | SMP Only |  | | | | | | | | | |
Canvas Firmware Feature Support | ||||||||||||
OTA FW Update | MicroPython Engine | Filesystem | RTOS Shell | Xbit VS Code | AT Command Set | Host Driver | DAPLink | Xbit Desktop | Xbit Mobile | |||
Sera NX040 | | | | | | | | | | | ||
Sera NX040 DVK Features
RGB LED
The Sera NX040 DVK has an RGB LED strip interface with a single RGB LED onboard and a header allowing you to attach an external string of LEDs for further output capability. Use the canvas.LEDStrip API to control the addressable RGB LED and optional LED strip if you have one attached. This port is compatible with typical WS2812B style LED strips. Note that J19 Pin 1 is the “square” pad (bottom pin in the image above). To attach an addressable RGB LED strip, connect J19 Pin 1 to V+, J19 Pin 2 to DI and J19 Pin 3 to GND on the LED strip.
The Sera NX040 DVK LED is accessible using the canvas.LEDStrip class from Python. Here is an example showing how to initialize the RGB LED strip and set the first LED (the LED onboard the DVK) to red:
>>> import canvas
>>> leds = canvas.LEDStrip("", 8)
>>> leds.set(0, canvas.LEDStrip.COLOR_RED)User Button
The Sera NX040 DVK has a single USER Buttonthat can be used by your Python script applications to interact with the program flow as your application requires via the GPIO interface. Use the machine.Pin API to detect the state of the button or setup an event on a rising/falling edge.
The Sera NX040 DVK user button is named “GPIO7” when accessing it from Python. Here is an example showing how to initialize the user button and read its value:
>>> import machine
>>> user = machine.Pin("GPIO7", machine.Pin.IN, machine.Pin.PULL_UP)
>>> user.value()
1MikroBUS Socket
The Sera NX040 DVK provides a single mikroBUS socket making it easy to experiment with mikroE Click boards for easily adding sensors and other external accessories through GPIO, I2C or SPI interface. Use the machine.I2C, machine.SPI and machine.Pin APIs as appropriate to interact with the Click board you install.
QWIIC Header
The Sera NX040 provides a single QWIIC header/port allowing you to plug in a QWIIC accessory board to interact from Python using the I2C interface. Use the machine.I2C API to interact with QWIIC attached devices.
More Resources
To continue learning more about how to use your Sera NX040 DVK for applications such as Two-Way-Ranging, see the Sera NX040 product page for links to application notes and articles highlighting what is possible with UWB ranging when coupled with BLE!