Getting Started with the DFU Python Script#

The DFU Python script is an NCP host application running on a system with a Python interpreter, and the application requires the Bluetooth mesh stack running in NCP mode on a Silicon Labs device connected to the system. Two or more additional Silicon Labs devices running the DFU examples are needed to perform a device firmware update. To run the DFU examples provided in the Bluetooth Mesh SDK, see Bluetooth Mesh Device Firmware Update Example Walkthrough.

Requirements#

The following is required to run the DFU Python script.

  • One mainboard with a supported board installed for the NCP target application.

  • Simplicity Studio 5

  • Gecko SDK Suite 4.2.2 (Bluetooth Mesh SDK 4.2.0) or later, distributed through Simplicity Studio 5. The prebuilt demos and examples are included in the SDK.

  • A host system with a Python interpreter, such as MacOS, Linux, or Windows.

  • The Python package PyBGAPI installed in the host system.

To install PyBGAPI, run:

pip3 install pybgapi

Run pip3 list. The pybgapi package should be version 1.2.0 or later:

Package     Version
----------  -------
...
pybgapi     1.2.0
pyserial    3.5
...

Bluetooth Mesh – NCP Empty v1.1 Application#

The Bluetooth Mesh – NCP Empty v1.1 example application is the target application running on a Silicon Labs device. The application is provided as a prebuilt demo binary image, ready to download and use, and a corresponding example project that you can modify and then build for the target part. If you want to build your own projects based on the example project, see the Getting Started Guide. This section describes how to install the prebuilt demo binary to the device.

The precompiled demos are only available for a limited set of parts, including selected EFR32xG13 and xG21 parts and BGM13 and MGM21 modules. The examples can be built for any part supported by the Bluetooth Mesh SDK.

Note: EFR32xG22 parts can run the Bluetooth Mesh – NCP Empty v1.1 example but do not support provisioner functionality.

  1. Open Simplicity Studio 5 with a compatible SoC wireless kit connected to the computer.

  2. Select the part in Debug Adapters view to open the Launcher perspective.

  3. Click the Example Projects & Demos tab.

  4. To see only the demos, turn off the Example Projects.

  5. Under Technology Type, filter on Bluetooth Mesh. Next to Bluetooth Mesh – NCP Empty v1.1, click RUN.

    screenshotscreenshot

DFU Python Script#

The DFU Python script is the host application running on a computer. Connect the Silicon Labs device running the Bluetooth Mesh – NCP Empty v1.1 example application to the computer on a USB port. Check the serial port information for the connected device.

On Windows, you can find the serial port number in Device Manager, e.g. COM7.

On Linux, you can run the ls /dev/ttyS* command in a terminal to list the device file, e.g. /dev/ttyS0.

On MacOS, you can run the ls /dev/tty.usb* command in a terminal to list the device file, e.g. /dev/tty.usbmodem0004401234561.

Open a terminal and change the directory to the path app/btmesh/example_host/btmesh_host_dfu of Gecko SDK. Run python3 btmesh_host_dfu.py --usb <usb> and you should not get any error message.

python3 btmesh_host_dfu.py --usb /dev/tty.usbmodem0004401234561

If you are running the script in a directory other than the path to the script folder under Gecko SDK, you need to specify the API files with the --xapi option.

python3 btmesh_host_dfu.py --usb /dev/tty.usbmodem0004401234561 --xapi /Users/<user>/SimplicityStudio/SDKs/gecko_sdk/protocol/bluetooth/api/sl_bt.xapi --xapi /Users/<user>/SimplicityStudio/SDKs/gecko_sdk/protocol/bluetooth/api/sl_btmesh.xapi

The script generates 3 files on the first run:

  • btmesh_host_dfu_cfg.ini: the configuration file the script reads to set command parameters and settings of model profiles. The script generates default values of the configuration options in the script if the configuration file doesn't exist.

  • btmesh_host_dfu_persistence.json: the script saves its persistent states to the file and loads data from the file on each CLI command and interactive session.

  • btmesh_host_dfu.log: the log file of the script's executions containing what BGAPI commands and events the script has sent and received. The log file could be helpful when something went wrong.

The script provides command line and interactive modes. You can run the script with the --help option to see the script usage and command descriptions in command line mode. The demonstration in Firmware Update Demonstration Using the DFU Python Script will run the script in interactive mode.

python3 btmesh_host_dfu.py --usb /dev/tty.usbmodem0004401234561 --interactive