X-CUBE-IOTA1 Expansion Software Package for STM32Cube User Manual

UM2606
User manual

Getting started with the IOTA Distributed Ledger
Technology software expansion for STM32Cube

Introduction

The X-CUBE-IOTA1 expansion software package for STM32Cube runs on the STM32 and includes middleware to enable the IOTA Distributed Ledger Technology (DLT) functions.
The IOTA DLT is a transaction settlement and data transfer layer for the Internet of Things (IoT). IOTA allows people and machines to transfer money and/or data without any transaction fees in a trustless, permissionless and decentralized environment. This technology even makes micro-payments possible without the need of a trusted intermediary of any kind. The expansion is built on STM32Cube software technology to ease portability across different STM32microcontrollers. The current version of the software runs on the B -L4S5I-IOT01A Discovery kit for IoT node and connects to the Internet through the attached Wi-Fi interface.

RELATED LINKS

Visit the STM32Cube ecosystem web page on www.st.com for further information
https://www.iota.org/get-started/what-is-iota
https://docs.iota.org/docs/getting-started/1.1/introduction/overview
https://iota-beginners-guide.com
https://chrysalis.docs.iota.org
https://iota-beginners-guide.com/future-of-iota/iota-1-5-chrysalis
https://www.boazbarak.org/cs127/Projects/iota.pdf

Acronyms and abbreviations

Table 1. List of acronyms

X-CUBE-IOTA1 software expansion for STM32Cube

Overview

The X-CUBE-IOTA1 software package expands STM32Cube functionality with the following key features:

• Complete firmware to build IOTA DLT applications for STM32-based boards

• Middleware libraries featuring:
  – FreeRTOS
  – Wi-Fi management
  – encryption, hashing, message authentication, and digital signing (Cryptolib)
  – transport-level security (MbedTLS)
  – IOTA Client API for interacting with the Tangle

• Complete driver to build applications accessing motion and environmental sensors

• Examples to help understand how to develop an IOTA DLT Client application

• Easy portability across different MCU families, thanks to STM32Cube

• Free, user-friendly license terms

The software expansion provides the middleware to enable the IOTA DLT on an STM32 microcontroller. The IOTA DLT is a transaction settlement and data transfer layer for the Internet of Things (IoT). IOTA allows people and machines to transfer money and/or data without any transaction fees in a trustless, permissionless and decentralized environment. This technology even makes micro-payments possible without the need of a trusted intermediary of any kind.

IOTA 1.0

Distributed Ledger Technologies (DLTs) are built on a node network which maintains a distributed ledger, which is a cryptographically secured, distributed database to record transactions. Nodes issue transactions through a consensus protocol.
IOTA is a distributed ledger technology specifically designed for IoT.
The IOTA distributed ledger is called the tangle and is created by the transactions issued by the nodes in the IOTA network.
To publish a transaction in the tangle, a node has to:

1. validate two unapproved transactions called tips
2. create and sign the new transaction
3. perform sufficient Proof-of-Work
4. broadcast the new transaction to the IOTA network

The transaction is attached to the tangle together with two references pointing to the validated transactions.
This structure can be modelled as a directed acyclic graph, where the vertices represent single transactions and the edges represent references among pairs of transactions.
A genesis transaction is at the tangle root and includes all the available IOTA tokens, called iotas.
IOTA 1.0 uses a rather unconventional implementation approach based on trinary representation: every element in IOTA is described using trits = -1, 0, 1 instead of bits, and trytes of 3 trits instead of bytes. A tryte is represented as an integer from -13 to 13, encoded using letters (A-Z) and number 9.
IOTA 1.5 (Chrysalis) replaces the trinary transaction layout with a binary structure.
The IOTA network includes nodes and clients. A node is connected to peers in the network and stores a copy of the tangle. A client is a device with a seed to be used to create addresses and signatures.
The client creates and signs transactions and sends them to the node so that the network can validate and store them. Withdrawing transactions must contain a valid signature. When a transaction is considered valid, the node adds it to its ledger, updates the balances of the affected addresses and broadcasts the transaction to its neighbours.

IOTA 1.5 – Chrysalis

The objective of the IOTA Foundation is to optimize the IOTA main net before Coordicide and to offer an enterprise-ready solution for the IOTA ecosystem. This is achieved by an intermediate update called Chrysalis. The main upgrades introduced by Chrysalis are:

• Reusable addresses: the adoption of the Ed25519 signature scheme, replacing the Winternitz one time signature scheme (W-OTS), allows the users to safely send tokens from the same address several times;
• No more bundles: IOTA 1.0 uses the concept of bundles to create transfers. Bundles are a set of transactions linked together by their root reference (trunk). With the IOTA 1.5 update, the old bundle construct is removed and replaced by the simpler Atomic transactions. The Tangle vertex is represented by the Message which is a sort of container that can have arbitrary payloads (i.e., Token payload or Indexation payload);
• UTXO model: originally, IOTA 1.0 used an account-based model for tracking individual IOTA tokens: each IOTA address held a number of tokens and the aggregated number of tokens from all IOTA addresses was equal to the total supply. Instead, IOTA 1.5 uses the unspent transaction output model, or UTXO, based on the idea of tracking unspent amounts of tokens via a data structure called output;
• Up to 8 Parents: with IOTA 1.0, you always had to reference 2 parent transactions. With Chrysalis, a greater number of referenced parent nodes (up to 8) is introduced. To obtain the best results, at least 2 unique parents at a time are recommended.

RELATED LINKS
For more information about Chrysalis, please refer to this documentation page

Proof-of-Work

The IOTA protocol uses Proof-of-Work as a means to rate-limit the network.
IOTA 1.0 used the Curl-P-81 trinary hash function and required a hash with the matching number of trailing zero trits to issue a transaction to the Tangle.
With Chrysalis, it is possible to issue binary messages of arbitrary size. This RFC describes how to adapt the existing PoW mechanism to the new requirements. It aims at being as less disruptive as possible to the current PoW mechanism.

Architecture

This STM32Cube expansion enables development of applications accessing and using the IOTA DLT middleware.
It is based on the STM32CubeHAL hardware abstraction layer for the STM32 microcontroller and extends STM32Cube with a specific board support package (BSP) for the microphone expansion board and middleware components for audio processing and USB communication with a PC.
The software layers used by the application software to access and use the microphone expansion board are:

• STM32Cube HAL layer: provides a generic, multi-instance set of APIs to interact with the upper layers (the application, libraries and stacks). It consists of generic and extension APIs based on a common architecture which allows other layers like the middleware layer to function without specific Microcontroller Unit (MCU) hardware configurations. This structure improves library code reusability and guarantees easy device portability.
• Board Support Package (BSP) layer: is a set of APIs which provides a programming interface for certain board specific peripherals (LED, user button etc.). This interface also helps in identifying the specific board version and provides support for initializing required MCU peripherals and reading data.

Figure 1. X-CUBE-IOTA1 software architecture

Folder structure

Figure 2. X-CUBE-IOTA1 folder structure

The following folders are included in the software package:

• Documentation: contains a compiled HTML file generated from the source code and detailed documentation of the software components and APIs
• Drivers: contains the HAL drivers and the board-specific drivers for supported board and hardware platforms, including those for the on-board components and the CMSIS vendor-independent hardware abstraction layer for the ARM® Cortex®-M processor series
• Middlewares: contains libraries featuring FreeRTOS; Wi-Fi management; encryption, hashing, message authentication, and digital signing (Cryptolib); transport-level security (MbedTLS); IOTA Client API to interact with the Tangle
• Projects: contains examples to help you develop an IOTA DLT Client application for the supported STM32based platform (B-L4S5I-IOT01A), with three development environments, IAR Embedded Workbench for ARM (EWARM), RealView Microcontroller Development Kit (MDK-ARM) and STM32CubeIDE

API

Detailed technical information with full user API function and parameter description are in a compiled HTML file in the “Documentation” folder.

IOTA-Client application description

The project files for the IOTA-Client application can be found in: $BASE_DIR\Projects\B-L4S5IIOT01A\Applications\IOTA-Client.
Ready-to-build projects are available for multiple IDEs.
The user interface is provided via serial port and must be configured with the following settings:

Figure 3. Tera Term – Terminal setup

Figure 4. Tera Term – Serial port setup

To run the application, follow the procedure below.
Step 1. Open a serial terminal to visualize the log of messages.
Step 2. Enter your Wi-Fi network configuration (SSID, Security Mode, and password).
Step 3. Set the TLS root CA certificates.
Step 4. Copy and paste the contents of Projects\B-L4S5I- IOT01A\Applications\IOTAClient\usertrust_thetangle.pem. The device uses them to authenticate the remote hosts through TLS.

Note: After configuring the parameters, you can change them by restarting the board and pushing the User button (blue button) within 5 seconds. This data will be saved in the Flash memory.

Figure 5. Wi-Fi parameter settings

Step 5. Wait for the message “Press any key to continue” to appear. The screen is then refreshed with the list of the main functions:

• Send a generic indexation message
• Send an indexation sensor message (including timestamp, Temperature, and Humidity)
• Get balance
• Send Transaction
• Other functions

Figure 6. Main menu

Step 6. Choose option 3 to test one of the following functions:

Figure 7. Other functions

RELATED LINKS
For further details about IOTA 1.5 functions, refer to the IOTA C Client documentation

System setup guide

Hardware description

STM32L4+ Discovery kit IoT node

The B-L4S5I-IOT01A Discovery kit for IoT node allows you to develop applications to directly connect to cloud servers.
The Discovery kit enables a wide variety of applications by exploiting low- power communication, multi-way sensing and ARM®Cortex® -M4+ core-based STM32L4+ series features.
It supports Arduino Uno R3 and PMOD connectivity providing unlimited expansion capabilities with a large choice of dedicated add-on boards.

Figure 8. B-L4S5I-IOT01A Discovery kit

Hardware setup

The following hardware components are needed:

1. one STM32L4+ Discovery kit for IoT node equipped with Wi-Fi interface (order code: B-L4S5I-IOT01A)
2. a USB type A to Mini-B USB Type B cable to connect the STM32 discovery board to the PC

Software setup

The following software components are needed to set up the development environment for creating IOTA DLT applications for the B-L4S5I-IOT01A:

• X-CUBE-IOTA1: firmware and related documentation is available on st.com
• development tool-chain and compiler: the STM32Cube expansion software supports the following environments:
  – IAR Embedded Workbench for ARM ® (EWARM) toolchain + ST-LINK/V2
  – RealView Microcontroller Development Kit (MDK-ARM) toolchain + ST-LINK/V2
  – STM32CubeIDE + ST-LINK/V2

System setup

The B-L4S5I-IOT01A Discovery board allows the exploitation of the IOTA DLT features. The board integrates the ST-LINK/V2-1 debugger/programmer. You can download the relevant version of the ST-LINK/V2-1 USB driver at STSW- LINK009.

Revision history

Table 2. Document revision history

Sending data through zero-value
transactions and Section 3.4.8.4 Sending funds through transfer transactions.
6-May-21| 3| Updated Introduction, Section 1 Acronyms and abbreviations, Section 2.1 Overview, Section 2.1.1 IOTA 1.0, Section 2.1.3 Proof-of-Work, Section 2.2 Architecture, Section 2.3 Folder structure, Section 3.2 Hardware setup, Section 3.3 Software setup and Section 3.4 System setup.
Removed Section 2 and replaced by a link in the Introduction.
Removed Section 3.1.2 Transactions and bundles, Section 3.1.3 Account and signatures, Section
3.1.5 Hashing. Section 3.4 How to write applications and related sub-sections, Section 3.5 IOTALightNode application description and related subsections, and Section 4.1.1 STM32
Nucleo platform Added Section 2.1.2IOTA 1.5 – Chrysalis, Section 2.5 IOTA- Client application description, Section 2.4 API and Section 3.1.1 STM32L4+ Discovery kit IoT node.

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks. All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2021 STMicroelectronics – All rights reserved

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>