PyCOM Blueprint

The Pycom onboarding blueprint enables a PySense, in combination with GPy, to communicate with the AWS IoT Core. This enables the functionality to subscribe and publish messages on the IoT Core, by making use of the SIM (IoT Device) specific certificates and keys.

• Prerequisites
  • Firmware
  • 1NCE SIM
• Configuration
• Examples
• Code
• Translation templates

Prerequisites

Firmware

Before executing the onboarding blueprint on your PyCom device it is needed to upgrade the device to the newest firmware version. The firmware can be upgraded by following the steps below:

• Update the board by doing a manual firmware update, following the official guide from PyCom https://docs.pycom.io/index.html .
• Upgrade the firmware by making use of the PyCom update firmware tool https://docs.pycom.io/updatefirmware/device/ .

For our examples, we made use of the following firmware version: 1.20.2.r1

1NCE SIM

An activated SIM Card is needed before it is possible to execute the onboarding blueprint on your device. This is required to load in the needed certificates and keys to set up the connection to the AWS IoT Core on the device.

Configuration

The onboarding script configuration can be found in config.py in the root folder of the blueprint.

• Onboarding Configuration

ON_BOARDING_URL: URL used to perform the onboarding call

• IoT Core Configuration

CONN_DISCONNECTION_TIMEOUT: Connection disconnection timeout in seconds

MQTT_OPERATION_TIMEOUT: Connection time out to the MQTT IoT Core broker in seconds

MQTT_TOPIC_NAME: MQTT Topic name

• File location Configuration

ROOT_CA_PATH: Root CA file path

PRIVATE_KEY_PATH: Private key file path

CERTIFICATE_PATH: Certificate file path

• UDP Endpoint Configuration

UDP_ENDPOINT_ADDRESS: UDP Endpoint URL

UDP_ENDPOINT_PORT: Port used for the UDP Endpoint

CoAP Server Configuration

COAP_SERVER_PORT: Port used for setting up the CoAP Server

COAP_POST_POLL_TIME: Time in milliseconds that the CoAP Server needs to pull till a new message arrives

• CoAP Endpoint Configuration

COAP_ENDPOINT_ADDRESS: CoAP Resource endpoint address

COAP_ENDPOINT_PORT: CoAP Endpoint port

COAP_TOPIC_NAME: CoAP Topic Name

COAP_ENDPOINT_PATH: CoAP Endpoint path

• Translation Location

GPS_TRANSLATION_DATA_PATH: GPS Translation example data file path

ENV_DATA_COLLECTOR_TRANSLATION_DATA_PATH: Environment Data Collector example data file path

• Message Interval

MESSAGE_INTERVAL_SECONDS: Interval in which messages are sent

# -*- coding: utf-8 -*-
""""
    On boarding Configuration
"""
ON_BOARDING_URL = 'https://device.connectivity-suite.cloud/device-api/onboarding'

""""
    Iot Core Configuration
"""
CONN_DISCONNECTION_TIMEOUT = 5
MQTT_OPERATION_TIMEOUT = 5
MQTT_TOPIC_NAME = 'hello-world'

""""
    File location configuration
"""
PRIVATE_KEY_PATH = '/flash/client.private.key'
CERTIFICATE_PATH = '/flash/client.cert.pem'
ROOT_CA_PATH = '/flash/root-CA.crt'

""""
    UDP Endpoint configuration
"""
UDP_ENDPOINT_ADDRESS = 'udp.connectivity-suite.cloud'
UDP_ENDPOINT_PORT = 4445

""""
    CoAP Server Configuration
"""
COAP_SERVER_PORT = 5683
COAP_POST_POLL_TIME = 2000

""""
    CoAP Endpoint Configuration
"""
COAP_ENDPOINT_ADDRESS = 'coap.connectivity-suite.cloud'
COAP_ENDPOINT_PORT = 5683
COAP_TOPIC_NAME = 'hello-world'
COAP_ENDPOINT_PATH = '/'

""""
    Translation Location
"""
GPS_TRANSLATION_DATA_PATH = '/flash/lib/translator/gps_data.txt'
ENV_DATA_COLLECTOR_TRANSLATION_DATA_PATH = '/flash/lib/translator/env_data_coll_data.txt'

""""
    Message Interval
"""
MESSAGE_INTERVAL_SECONDS = 60

Examples

The blueprint consists of multiple example scripts for different use-cases, like publishing a message to the IoT Core. To run the chosen script on the device, the script needs to be renamed to main.py and located within the root directory of the /flash on the device.

The following test scripts are available:

• Publish and subscribe a message to an IoT Core Topic
• Send a UDP message
• Send a GPS Translation message
• Send an Environment Data Collector message
• Send a CoAP POST request

Publish and Subscribe to the AWS IoT Core example (main.py)

Within the publish and subscribe to the AWS IoT Core example script the following steps are executed:

• Load in the configuration variables
• Starts onboarding process
  -- Retrieves device-specific configuration (Certificates, etc.)
  -- Download the Root CA based on the given URL
  -- Saves all keys and certificates to the local file system

• Connect to the IoT Core with the given certificate, private key, and Root CA certificate
• Subscribe on the <ICCID>/hello-world topic
• Publish a Hello-world message on the <ICCID>/hello-world topic
• Close MQTT Connection
• Close network Connection
• Put the PyCom in idle mode/low-power mode

Send UDP message example (main_udp.py)

Within the send UDP message example script the following steps are executed:

• Load in the configuration variables
• Perform a DNS Resolution
• Send a Message over a UDP Socket
• Close network Connection
• Put the PyCom in idle mode/low-power mode

Send a GPS Translation message example (main_gps_translation.py)

Within the send a GPS Translation message example script the following steps are executed:

• Load in the configuration variables
• Read the example data file
• Convert data to a bytes message
• Perform a DNS Resolution
• Send a Message over a UDP Socket
• Close network Connection
• Put the PyCom in idle mode/low-power mode

Send an Environment Data Collector message example (main_env_translation.py)

Within the send an Environment Data Collector example script the following steps are executed:

• Load in the configuration variables
• Read the example data file
• Convert data to a bytes message
• Perform a DNS Resolution
• Send a Message over a UDP Socket
• Close network Connection
• Put the PyCom in idle mode/low-power mode

Send a CoAP Post Request (main_coap.py)

Within the send a CoaP post request example script the following steps are executed:

• Load in the configuration variables
• Setup the CoAP Client
• Register a Message Received callback function
• Start the CoAP Client
• Post a CoAP request to the 1NCE CoAP Server
• Poll for incoming messages (Polling for the confirmation message)
• Close network Connection
• Put the PyCom in idle mode/low-power mode

Code

Network connector (network_connector.py)

Functions

• Attach (_attach)
  Attaches to the 1NCE network (1nce.iot.net)

• Connect (connect)
  First attaches and then connects to the 1NCE network

• Disconnect (disconnect)
  Disconnects from the 1NCE network,

• Get reception (get_reception)
  Gets the current reception to the 1NCE network.

• Get IP Address (get_ip_address)
  Gets the IP Address from the modem

Onboard Service (onboard_service.py)

Variables

• endpoint: Onboard service endpoint URL, like https://device.connectivity-suite.cloud/device-api/onboarding
• private_key_path: Private key file path
• certificate_pem_path: Client certificate file path
• root_ca_crt_path: Root CA certificate file path

Functions

• Onboard ( on_board )
  Onboards the device by getting the needed variables to connect to the IoT Core.

• Get device information ( _get_device_information )
  Gets the device information from the onboarding endpoint.

• Save data ( _save_data )
  Saves the data (certificates & keys) to the local file storage.

• Save private key ( _save_private_key )
  Saves the private key to the local file storage.

• Save certificate (_save_certificate_pem)
  Saves the client certificate to the local file storage.

• Save Root CA certificate(_save_root_ca_crt)
  Saves the root CA certificate to the local file storage.

Root CA Certificate Downloader (download_root_ca.py)

Variables

• root_ca_url: Root CA URL, like https://www.amazontrust.com/repository/AmazonRootCA1.pem.

Functions

Download (download)

Downloads the Root CA.

AWS IoT Controller (aws_iot_controller.py)

Variables

• endpoint: Endpoint URL to the IoT Core, like: <IoT_Core_ID>.<AWS_region>.amazonaws.com.
• client_certificate: Client certificate path (.pem).
• private_key: Client private key path (.key)
• root_ca: Root CA path (.crt)
• client_id: Client identifier for the IoT Core, this is the ICCID of the used SIM.
• conn_disconnect_timeout: Connection disconnect time-out, in seconds, to the IoT Core.
• mqtt_oper_timeout: Time-out for operations to the IoT Core MQTT broker

Functions

• Initialize (initialize)
  Initialize and connect to the IoT Core. The following steps are executed within this method:

• Configure the endpoint URL

• Configure the credentials, based on the set certificates and keys

• Configure the different timeouts

• Connect to the IoT Core

• Subscribe (subscribe)
  Subscribe to an IoT Core Topic. Received messages will then be logged to the console via the _on_message_received method.

• Unsubscribe (unsubscribe)
  Unsubscribe to an IoT Core Topic.

• Publish (publish)
  Publish a message to an IoT Core Topic, these topics have the following structure: /, where is the topic name that was passed to the method.

• Disconnect (disconnect)
  Disconnect the device from the IoT Core.

• On message received (_on_message_received)
  Handler to process message(s) that are received on a specific topic. It processes incoming messages and logs them to the console.

Message Service (message_service.py)

Functions

• Fill bytes (fill_bytes)
  Method to fill a byte array on the corresponding start and end byte length.

CoAP Service (coap_service.py)

Functions

• Initialize (initialize)
  Initializes and starts the CoAP Client

• Set Message Callback Method (set_message_callback_method)
  Sets the message callback method that needs to be used, this method is used to process the incoming CoAP responses on the CoAP Client

• Post a CoAP Request (post)
  Posts a CoAP request to the given server with the given content type

• Poll (poll)
  Polls for new incoming CoAP messages on the client will then send these messages to the callback method.

Translation templates

The project also has a translator folder, which can be found by following the path: /nce/translator. It contains sample CSV data files and also a JSON translator template for GPS navigation and Environment data collector examples.