Python Tools

Gateways

Utilise gateway scripts to interact with Infuse-IoT Powered devices.

The python gateway tools act as a bridge between local Infuse-IoT devices and other tools running on the computer. Currently the gateways support interaction with devices connected directly via a serial port, or directly over Bluetooth.

Bluetooth connectivity can be provided:

Via an Infuse-IoT powered embedded device with the infuse gateway tool. (Preferred) or
Directly via your machines native PC Bluetooth libraries with the infuse native_bt tool
Using infuse native_bt requires compatible hardware with Bluetooth 5.0 and support advertising extension capabilities. See below for more details.

---
toolbar:
  title: How Python tools use gateway connections to connect to Infuse-IoT devices
---
flowchart LR
    Tool["Python tool<br/>(RPC runner, OTA upgrade, etc.)"]
    Gateway["infuse gateway"]
    DeviceGateway["Infuse-IoT device<br/>running gateway_usb"]
    NativeBT["infuse native_bt"]
    DeviceBT["Infuse-IoT device"]

    Tool <-->|UDP| Gateway
    Gateway <-->|Serial| DeviceGateway
    Gateway <-->|RTT| DeviceGateway
    Gateway <-->|PyOCD| DeviceGateway
    DeviceGateway <-->|Bluetooth| DeviceBT
    Tool <-->|UDP| NativeBT
    NativeBT <-->|Bluetooth| DeviceBT

Both tools are designed to run persistently in the background, managing connections to remote devices, forwarding packets out to Infuse-IoT hardware and broadcasting received data on localhost multicast UDP sockets.

Gateway tools rely on an Infuse-IoT API Key and any Custom Network Keys and definitions being provided through the Credentials command.

Common Functionality

Both gateway tools have common configuration options

`--server-port`: Server Port

The --server-port argument is used to run more than one instance of infuse gateway concurrently on the same machine.

When specifying --server-port, the port must be an odd number.

The Gateway tools act as a bridge facilitating multiple other tools to access Infuse-IoT devices. It does so by utilising socket communications (multicast UDP). As a result of multicast UDP behaviours, by default only one instance of infuse gateway can run at a time.

---
    toolbar:
      title: How Python tools use gateway connections to connect to Infuse-IoT devices
    ---
    flowchart LR
        RpcTool["Tool: RPC runner"]
        OtaTool["Tool: OTA upgrade"]
        SyncTool["Tool: Data Logger Sync"]
        UdpPort["Multicast <br>UDP Port: 8751<br>(and 8752)"]
        Gateway1["infuse gateway"]
        Gateway2["infuse gateway"]
        DeviceGateway1["Device1"]
        DeviceGateway2["Device2"]

        RpcTool <--> UdpPort
        OtaTool <--> UdpPort
        SyncTool <--> UdpPort
        UdpPort <--> | Bind | Gateway1
        UdpPort x-- "`**Bind<br>Fail**`" --x Gateway2
        Gateway1 <--> DeviceGateway1
        Gateway2 <--> DeviceGateway2

The --server-port argument can be added to enable the operation multiple gateways concurrently on the same machine. By providing a different server port, the gateway can run independently of other gateway scripts at the same time. Similarly, additional tools can be supplied with a --server-port argument to use a different gateway instance (instead of the default).

---
    toolbar:
      title: How Python tools use gateway connections to connect to Infuse-IoT devices
    ---
    flowchart LR
        RpcTool["Tool: RPC runner"]
        RpcTool2["Tool: RPC runner (2)"]
        OtaTool["Tool: OTA upgrade"]
        SyncTool["Tool: Data Logger Sync"]
        UdpPort["Multicast <br>UDP Port: 8751<br>(and 8752)"]
        UdpPort2["Multicast <br>UDP Port: 8753<br>(and 8754)"]
        Gateway1["infuse gateway"]
        Gateway2["infuse gateway"]
        DeviceGateway1["Device1"]
        DeviceGateway2["Device2"]

        RpcTool <--> UdpPort
        RpcTool2 <--> UdpPort2
        OtaTool <--> UdpPort
        SyncTool <--> UdpPort
        UdpPort <--> | Bind | Gateway1
        UdpPort2 <--> | Bind | Gateway2
        Gateway1 <--> DeviceGateway1
        Gateway2 <--> DeviceGateway2

`--root`: Key File

In some instances, Tags utilise a Root Identity that is different from that provided by the Infuse-IoT Cloud. In such instances, utilising the default Cloud for authentication will cause cryptography to fail.

As a result, a root identity certificate can be provided to override the default Cloud identity with the --root argument.

Native Bluetooth

Native Bluetooth support is supported through the cross platform bleak package.

> infuse native_bt -h
usage: infuse native_bt [-h] [--root ROOT] [--server-port SERVER_SOCK]

Use the local Bluetooth adapter for Bluetooth interaction

options:
  -h, --help            show this help message and exit
  --root ROOT           Root identity certificate to use instead of cloud
  --server-port SERVER_SOCK
                        Alternate port to use for Gateway connections (default
                        8751)

Your machine must support the required Bluetooth Hardware Requirements to use infuse native_bt.

native_bt is convenient, however uses the Operating System's managed Bluetooth APIs. As a result, OS power saving policies can and will interfer with the tool's functionality.

Follow the instructions below to check compatibility.

Ensure your Bluetooth Adaptor supports Bluetooth 5.0 and advertising extensions.

Some older Bluetooth hardware might be compatible, but might not work out of the box.
Updating Bluetooth Drivers may help.

Native Bluetooth is not available when using WSL. Utilise the Infuse-IoT powered hardware options instead.

All Arm Silicon/aarch64 macOS devices support the Bluetooth requirements.

Support on Intel Mac devices will depend on hardware compatibility. As a result this has not been tested or supported.

On MacOS, native_bt currently relies on an undocumented IOBluetooth API

Embedded Devices

To create a bridge to a physically connected device, use the infuse gateway command. This command can be used both for firmrware applications that forward data over Bluetooth (such as infuse-sdk/apps/gateway_usb) or devices that only interact over the physical link, or even just to view device debug logs.

Supported backends

An appropriate physical connection interface (backend) must be provided to the tool depending on the physical connection:

> infuse gateway --help
usage: infuse gateway [-h] (--serial SERIAL | --rtt RTT | --pyocd PYOCD) [--display-only] [--log [filename]]

Connect to a gateway device over serial and route commands to Bluetooth devices

options:
  -h, --help            show this help message and exit
  --serial SERIAL       Gateway serial port
  --rtt RTT             RTT serial port
  --pyocd PYOCD         RTT via PyOCD
  --display-only, -d    No networking, only display serial
  --log [filename], -l [filename]
                        Save serial output to file
  --baud BAUD           Baudrate for serial port
  --root ROOT           Root identity certificate to use instead of cloud
  --server-port SERVER_SOCK
                        Alternate port to use for Gateway connections (default 8751)

--serial is used for standard serial ports (e.g. COMx, /dev/ttyACMx).
--rtt is used for RTT through pylink. The argument is the device name (e.g. nRF52840_xxAA)
--pyocd is used for RTT through pyocd. The argument is the device name (e.g. stm32l451ceux)

Store and manage Credentials used by the Infuse-IoT Python Tools.

Infuse-IoT Cloud support

Display information from Infuse Cloud along with creating new definitions.