edge-st-sdk 1.3.4

IoT edge computing abstraction library package.

EdgeST SDK

EdgeST SDK is an IoT edge computing abstraction library for Linux gateways. It relies on cloud platforms' edge SDKs to enable local execution of functions on a Linux gateway and synchronization to the cloud.

More specifically, it enables the creation of "virtual" devices on the gateway that map to non-IP connected devices (e.g. via Bluetooth Low Energy technology), and the corresponding "shadow" devices on the cloud. Local computation can be performed directly on the gateway with the same logic written for the cloud even when Internet connection is lost, and shadow devices will be synchronized to virtual devices as soon as Internet connection becomes available.

Currently Amazon AWS Greengrass edge computing service is supported, while other cloud engines will be added in the future.

Documentation

Documentation can be found here.

Compatibility

This version of the SDK is compatible with Python 3.5 and runs on a Linux system.

Preconditions

The SDK relies on the Amazon AWS Greengrass SDK, so please refer to the Amazon AWS Greengrass official documentation to install it. At the time of writing, this implies installing the following components:

1. Amazon AWS IoT Python SDK:

$ sudo pip3 install AWSIoTPythonSDK

2. Amazon AWS IoT Greengrass SDK, that will be downloaded when creating a "Group" on the AWS web IoT Console on the cloud. Further actions are required to setup the environment, so please follow the abovementioned official documentation. Moreover, please install the concurrent.futures module to run pools of threads in background, that serve listeners' callbacks.

$ sudo pip3 install futures

Last but not least, the Python version of the BlueST SDK is required to run the provided application examples.

Installation

The EdgeST SDK can be installed through the Python pip package manager.

$ sudo pip3 install edge-st-sdk

BlueST SDK

BlueST SDK is a multi-platform library available for Linux (beyond Android and iOS) that allows easy access to the data exported by a Bluetooth Low Energy (BLE) device that implements the BlueST Protocol.

The Linux version of the SDK, written in Python, is needed to let BLE devices connect to a Linux gateway. This enables IoT applications where BLE connected devices stream data to a gateway through the BlueST SDK, while the EdgeST SDK abstracts edge computing operations performed locally on the gateway and the synchronization to the shadow devices on the cloud.

Setting up the application examples

Before running the application examples, please prepare your devices as described here below:

• The example_ble_aws_1.py and the example_ble_aws_2.py application examples show how to handle two BLE devices implementing the BlueST Protocol that connect to a Linux gateway, and to make them communicate to the Amazon AWS IoT Cloud through the AWS Greengrass edge computing service. The former shows a usage of the "Switch" feature in such a way that pressing the user button on a device makes the LED of the other device toggle its status through a logic defined by the GG_Switch_Lambda.py lambda function. The latter adds the handling of environmental and inertial features so that data from Pressure, Humidity, Temperature, Accelerometer, Gyroscope, and Magnetometer sensors are sent to the IoT Cloud.

The applications require to set up two devices equipped with BLE connectivity, e.g.:

• Two NUCLEO-F401RE development boards
• Two X-NUCLEO-IDB05A1 Bluetooth Low Energy expansion boards
• Import the Node_BLE_Switch_Device or the Node_BLE_Sensors_Device mbed OS application to your ARM mbed account respectively for the first or the second application example, compile, and flash it onto the MCU board
• Edit the application example and set the "IOT_DEVICE_X_NAME" and "IOT_DEVICE_X_MAC" global variables properly (you can use a smartphone application to retrieve the MAC address)
• Put the certificates and the private keys of your devices into the folder on the Linux gateway specified by the "DEVICES_PATH" global variable
• Follow carefully the instructions described within the Examples_ble_aws.pdf application manual to configure the application on the cloud.

Running the application examples

To run the application examples please follow the steps below:

1. Install the EdgeST SDK as described by the Installation chapter.
2. Install the BlueST SDK as described by the Installation chapter.
3. Clone the EdgeST SDK git repository to download the application examples:

$ git clone https://github.com/STMicroelectronics/EdgeSTSDK_Python.git

4. Start the Greengrass daemon:

$ sudo /greengrass/ggc/core/greengrassd restart

5. Enter the "edge_st_examples" folder and run the desired script by providing the endpoint (i.e. IoT host) and the path of the root Certification Authority certificate. You can find these information within the "config.json" configuration file that comes from Amazon AWS when creating a Greengrass group (please refer to the Amazon AWS Greengrass official documentation), e.g.:

$ sudo python3 example_ble_aws_x.py -e <iot_host_prefix>.iot.<region>.amazonaws.com -r /greengrass/certs/root.ca.pem

License

COPYRIGHT(c) 2019 STMicroelectronics

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.