Canvas Networking (canvas_net)

The modules described in this chapter provide the interface to the network stack in products with networking support (MG100, BL5340 DVK, etc.).

The Canvas Software Suite products make use of standard MicroPython network modules wherever possible. The Zephyr-based products (MG100, Pinnacle 100, and BL5340 DVK) use the network module with a class named network.Zephyr. An application can bring up the network interface and wait for it to become available using:

nic = network.Zephyr()
nic.ifconfig("dhcp")
while nic.isconnected() == False:
    time.sleep_ms(250)

The Canvas Software Suite also implements the socket and ssl modules for communication with remote hosts.

Custom network modules supported by the Canvas Software Suite are documented below.

class canvas_net.Lwm2m

The Lwm2m class provides an interface to the LWM2M client. This class is a singleton, only one client can be instantiated at a time. Attempting to instantiate a second client will return the existing instance.

Parameters:: cb – Callback function to be called to report LWM2M RD client events to the application. The callback function takes a single integer parameter which is the LWM2M event that occurred (see the EV_LWM2M… constants).

create(resource: tuple, size: int = 0)

Create a LWM2M object instance, resource, or resource instance. The type to create is determined by the length of the resource tuple (2-tuple for object instance, 3-tuple for resource, 4-tuple for resource instance).

Parameters:

resource – A tuple containing the object ID, instance ID, and optionally resource ID and resource instance of the item to create.
size – The size of the resource to create in bytes. This is only used for resources and resource instances.

get_bytes(resource: tuple) → bytes

Get a LWM2M resource value as a bytes object.

Parameters:: resource – A 3- or 4-tuple containing the object ID, instance ID, resource ID, and optional resource instance ID of the resource to get.
Returns:: The value of the resource as bytes.

get_int(resource: tuple) → int

Get a LWM2M resource value as an integer.

Parameters:: resource – A 3- or 4-tuple containing the object ID, instance ID, resource ID, and optional resource instance ID of the resource to get.
Returns:: The value of the resource as an integer.

set(resource: tuple, value: any)

Set a LWM2M resource value.

If the provided value is an integer, the value of the resource is set to as an integer (either u8, u16, or u32 depending on the size of the resource). If the resource has a size that is not compatible with an integer, an exception is raised.

If the provided value is a bytes object, the bytes are copied into the resource. An exception is raised if the size of the bytes object is larger than the size of the resource.

If the provided value is a string, the characters are copied into the resource. An exception is raised if the size of the string is larger than the size of the resource.

Parameters:

resource – A 3- or 4-tuple containing the object ID, instance ID, and resource ID, and optional resource instance of the resource to set.
value – The value to set the resource to.

set_endpoint_name(name: str)

Set the LWM2M endpoint name.

Parameters:: name – The endpoint name to set.

set_exec_handler(resource: tuple, handler: any)

Set a LWM2M resource execution handler.

Parameters:

resource – A 3-tuple containing the object ID, instance ID, and resource ID of the resource to set the handler for.
handler – The handler to be called whenever the resource is executed by the server.

start(bootstrap: bool)

Start the LWM2M client.

Parameters:: bootstrap – If True, bootstrap the LWM2M client. If False, do not bootstrap.

stop(deregister: bool = True)

Stop the LWM2M client.

Parameters:: deregister – If True, deregister from the LWM2M server. If False, do not deregister.

EV_RD_BOOTSTRAP_REG_COMPLETE: int

Bootstrap registration complete event.

EV_RD_BOOTSTRAP_REG_FAILURE: int

Bootstrap registration failure event.

EV_RD_BOOTSTRAP_TRANSFER_COMPLETE: int

Bootstrap transfer complete event.

EV_RD_DEREGISTER: int

Deregistration event.

EV_RD_DEREGISTER_FAILURE: int

Deregistration failure event.

EV_RD_DISCONNECT: int

Client disconnected event.

EV_RD_ENGINE_SUSPENDED: int

Engine suspended event.

EV_RD_NETWORK_ERROR: int

Network error event.

EV_RD_QUEUE_MODE_RX_OFF: int

Receive off event in queue mode.

EV_RD_REGISTRATION_COMPLETE: int

Registration complete event.

EV_RD_REGISTRATION_FAILURE: int

Registration failure event.

EV_RD_REG_TIMEOUT: int

Registration timeout event.

EV_RD_REG_UPDATE: int

Registration update event.

EV_RD_REG_UPDATE_COMPLETE: int

Registration update complete event.

OBJ_DEVICE: int

LWM2M device object ID.

OBJ_SECURITY: int

LWM2M security object ID.

OBJ_SERVER: int

LWM2M server object ID.

SECURITY_CERT: int

LWM2M security mode: Certificate mode.

SECURITY_CERT_EST: int

LWM2M security mode: Certificate mode with EST.

SECURITY_NOSEC: int

LWM2M security mode: NoSec mode.

SECURITY_PSK: int

LWM2M security mode: Pre-Shared Key mode.

SECURITY_RAW_PK: int

LWM2M security mode: Raw Public Key mode.

class canvas_net.Modem

The Modem class provides an interface to a modem device. This class is a singleton, only one client can be instantiated at a time. Attempting to instantiate a second modem will return the existing instance.

Example:

>>> def modem_cb(e: tuple):
...     print(e)
...
>>> modem = canvas_net.Modem(modem_cb)

Parameters:: cb – Callback function to be called when a modem event is received. The callback function must accept a single argument, which will be a named tuple of the form (event, data, string). event is the event id. data is a byte string of data associated with the event. data can be None. string is a string value associated with the event. string can be None. The value None can be passed to disable the callback.

at_cmd(cmd: str, timeout: int = 5, resp_len: int = 512) → any

Send an AT command to the modem.

Warning

This API should be used with caution. It is intended for advanced users. Breaking the modem driver operation is possible.

Parameters:

cmd – The AT command to send.
timeout – The timeout in seconds to wait for a response.
resp_len – The maximum length of the response.

Returns:

The string response from the modem. Empty string if no response.

get_firmware_version() → str

Get the firmware version of the modem.

Returns:: The firmware version.

get_functionality() → int

Get the modem functionality.

Returns:: The mode. 0 = minimal, 1 = full, 4 = Airplane.

get_iccid() → str

Get the ICCID of the modem SIM card.

Returns:: The ICCID.

get_imei() → str

Get the IMEI of the modem.

Returns:: The IMEI.

get_imsi() → str

Get the IMSI of the modem SIM card.

Returns:: The IMSI.

get_serial_number() → str

Get the serial number of the modem.

Returns:: The serial number.

power_off(): Power off the modem. To power the modem back on, call reset().

reset(): Reset and reconfigure the modem.

set_apn(apn: str)

Set the modem APN. The modem reboots after this command is issued.

Parameters:: apn – The APN to set.

set_bands(bands: str)

Set the modem bands. The modem reboots after this command is issued.

Parameters:

bands –

The bands to set. This string is a band bit mask.

Bit Mask	Band
000000 00000000 00000000	Not available
000000 00000000 00000001	LTE Band 1 (2000 MHz)
000000 00000000 00000002	LTE Band 2 (1900 MHz)
000000 00000000 00000004	LTE Band 3 (1800 MHz)
000000 00000000 00000008	LTE Band 4 (1700 MHz)
000000 00000000 00000010	LTE Band 5 (850 MHz)
000000 00000000 00000080	LTE Band 8 (900MHz) only for 453-00011 (External antenna)
000000 00000000 00000100	LTE Band 9 (1900MHz) NOT CERTIFIED
000000 00000000 00000200	LTE Band 10 (2100MHz) NOT CERTIFIED
000000 00000000 00000800	LTE Band 12 (700 MHz)
000000 00000000 00001000	LTE Band 13 (700 MHz)
000000 00000000 00010000	LTE Band 17 (700 MHz)
000000 00000000 00020000	LTE Band 18 (800MHz) NOT CERTIFIED
000000 00000000 00040000	LTE Band 19 (800MHz) NOT CERTIFIED
000000 00000000 00080000	LTE Band 20 (800MHz)
000000 00000000 01000000	LTE Band 25 (1900MHz) NOT CERTIFIED
000000 00000000 02000000	LTE Band 26 (800 MHz) NOT CERTIFIED
000000 00000000 04000000	LTE Band 27 (800 MHz) NOT CERTIFIED
000000 00000000 08000000	LTE Band 28 (700MHz)
000000 00000000 40000000	LTE Band 31 (450MHz) NOT CERTIFIED
000002 00000000 00000000	LTE Band 66 (1800MHz) only for 453-00011 (External antenna)
000080 00000000 00000000	LTE Band 72 (450MHz) NOT CERTIFIED
000100 00000000 00000000	LTE Band 73 (450MHz) NOT CERTIFIED
100000 00000000 00000000	LTE Band 85 (700MHz) NOT CERTIFIED
400000 00000000 00000000	LTE Band 87 (410MHz) NOT CERTIFIED
800000 00000000 00000000	LTE Band 88 (410MHz) NOT CERTIFIED

For example passing a value of “809189F” will set bands 1,2,3,4,5,8,12,13,17,20,28. Leading zeros are not required.

set_functionality(mode: int)

Set airplane, normal, or reduced functionality mode. NOTE: Airplane mode persists when reset.

Parameters:: mode – The mode to set. 0 = minimal, 1 = full, 4 = Airplane.

set_gps_rate(rate: int)

When rate is non-zero: Put modem into Airplane mode. Enable GPS and generate HL7800_EVENT_GPS events. When zero: Disable GPS and put modem into normal mode. NOTE: Airplane mode isn’t cleared when the modem is reset.

Parameters:: rate – The rate in seconds.

set_rat(rat: int)

Set the modem radio access technology (RAT). The modem reboots after this command is issued.

Parameters:: rat – The RAT to set. 0 = CAT-M1, 1 = CAT-NB1.

update_firmware(file: str)

Update the modem firmware.

Parameters:: url – The file path of the firmware image in the file system.

EVENT_ACTIVE_BANDS: int = 9

EVENT_APN_UPDATE: int = 2

EVENT_BANDS: int = 8

EVENT_FOTA_COUNT: int = 11

EVENT_FOTA_STATE: int = 10

EVENT_GPS: int = 13

EVENT_GPS_POSITION_STATUS: int = 14

EVENT_NETWORK_STATE: int = 1

EVENT_POLTE: int = 17

EVENT_POLTE_LOCATE_STATUS: int = 16

EVENT_POLTE_REGISTRATION: int = 15

EVENT_RAT: int = 7

EVENT_REVISION: int = 12

EVENT_RSSI: int = 3

EVENT_SINR: int = 4

EVENT_SITE_SURVEY: int = 18

EVENT_SLEEP_STATE: int = 6

EVENT_STARTUP_STATE: int = 5

EVENT_STATE: int = 19

MODE_AIRPLANE: int = 4

MODE_FULL: int = 1

MODE_MINIMAL: int = 0

STATE_FOTA_COMPLETE: int = 8

STATE_FOTA_FILE_ERROR: int = 5

STATE_FOTA_IDLE: int = 0

STATE_FOTA_INSTALL: int = 6

STATE_FOTA_PAD: int = 3

STATE_FOTA_REBOOT_AND_RECONFIGURE: int = 7

STATE_FOTA_SEND_EOT: int = 4

STATE_FOTA_START: int = 1

STATE_FOTA_WIP: int = 2

STATE_GPS_POSITION_2D_AVAILABLE: int = 3

STATE_GPS_POSITION_3D_AVAILABLE: int = 4

STATE_GPS_POSITION_FIXED_TO_INVALID: int = 5

STATE_GPS_POSITION_INVALID: int = -1

STATE_GPS_POSITION_LOST_OR_NOT_AVAILABLE_YET: int = 1

STATE_GPS_POSITION_PREDICTION_AVAILABLE: int = 2

STATE_GPS_STR_ALTITUDE: int = 5

STATE_GPS_STR_ALT_UNC: int = 6

STATE_GPS_STR_DIRECTION: int = 7

STATE_GPS_STR_FIX_TYPE: int = 3

STATE_GPS_STR_GPS_TIME: int = 2

STATE_GPS_STR_HEPE: int = 4

STATE_GPS_STR_HOR_SPEED: int = 8

STATE_GPS_STR_LATITUDE: int = 0

STATE_GPS_STR_LONGITUDE: int = 1

STATE_GPS_STR_VER_SPEED: int = 9

STATE_INITIALIZED: int = 1

STATE_NETWORK_EMERGENCY: int = 8

STATE_NETWORK_HOME_NETWORK: int = 1

STATE_NETWORK_NOT_REGISTERED: int = 0

STATE_NETWORK_OUT_OF_COVERAGE: int = 4

STATE_NETWORK_REGISTRATION_DENIED: int = 3

STATE_NETWORK_ROAMING: int = 5

STATE_NETWORK_SEARCHING: int = 2

STATE_NETWORK_UNABLE_TO_CONFIGURE: int = 240

STATE_NOT_READY: int = 0

STATE_SLEEP_AWAKE: int = 2

STATE_SLEEP_HIBERNATE: int = 1

STATE_SLEEP_LITE_HIBERNATE: int = 3

STATE_SLEEP_SLEEP: int = 4

STATE_SLEEP_UNINITIALIZED: int = 0

STATE_STARTUP_INACTIVE_SIM: int = 6

STATE_STARTUP_READY: int = 0

STATE_STARTUP_SIMLOCK: int = 3

STATE_STARTUP_SIM_NOT_PRESENT: int = 2

STATE_STARTUP_UNKNOWN: int = 5

STATE_STARTUP_UNRECOVERABLE_ERROR: int = 4

STATE_STARTUP_WAITING_FOR_ACCESS_CODE: int = 1