vitro-shard-sdk

• vitro-shard-sdk
  • Introduction
  • Features
  • Dependencies
  • Usage
  • Architecture
    • Division into modules
    • Event queues and callbacks
  • Typical cooperation of objects
  • Closed source static library
    • Building
    • Using
    • Known issues
  • Releasing SDK

Introduction

vitro-shard-sdk is a library based on mbed-os designed for developers of vitroio nodes firmware.

The library provides common nodes functionality and handles standard communication protocol with gateway i.e. initialization of communication and firmware upgrade.

For detailed guideline for firmware developers and examples please see firmware developers guide.

For detailed API documentation please see doc.

Features

• Simple communication over bus

  The library provides classes for bus frames and CAN bus with interfaces complied with defined communication protocol. The user has not to care about formatting the frame identifier. Provided type for bus frames allows to set particular element of the frame and the abstraction layer for CAN bus allows for directly sending/receiving of such frames.

• Handling predefined communication protocol

  The NodeController class hides predefined communication protocol from user. The user is not responsible for handling predefined bus frames e.g. initialization of communication with gateway, reporting firmware version etc. The NodeController class provides appropriate methods for such operations e.g. initCommunication, which cares about the whole process.

• Firmware upgrades support

  The upgrade of the firmware also belongs to predefined communication protocol. Therefore, all of the user has to do is to create NodeController object and initialize the communication with gateway to provide support for firmware upgrades. When the new firmware is available in the flash memory, the application will be reset automatically.

• Easy implementation of measurement system

  The sdk provides classes for easy construction of measurement system based on sensors chosen by the user. Developer has to implement AbstractSensorDriver and AbstractSensorInterface virtual classes to provide support of its sensors. Then, all to do is to create MeasurementApi object and configure it i.e. register implemented sensors interfaces, set polling time and set handler for measurement values. The MeasurementApi reads measurement parameters from all of registered sensors in set intervals and calls registered handler when the new values are read.

Dependencies

The library requires mbedOS version 6.16.0

Usage

• To the project sources should be included root directory of vitro-shard-sdk repository.

  All of library sources are placed in vitroio-sdk directory. Therefore headers should be included in user application with vitroio-sdk prefix. For example:

  #include <vitroio-sdk/communication/canbus.h>

• All of library components are placed in vitroio::sdk namespace.
• Classes placed in impl directories of modules folders should not be used in user application. Additionaly these components are also placed in impl namespace.

Architecture

Division into modules

The sdk is divided into functional modules. It allows to disable compilation of particular modules using .mbedignore file. However, some modules can require another ones for internal usage. For more information see detailed documentation.

Event queues and callbacks

All of modules which do some real time stuff, operate on an event queue. The user can choose if an object is to use external or internal event queue. However, on both cases the internal event queue is created but it is chained into external queue or handled by internal thread respectively. Priority of internal thread and size of internal queue determines the user. For more information about event queues of mbed please see About the mbed OS event loop.

All of events that the particular object can generate are handled by callbacks registered by the user.

Typical cooperation of objects

Typical cooperation of objects is presented in below scheme:

Closed source static library

Since 1.2.1 version it is possible to build closed-source Vitro Shard SDK as static library.

Building

Make sure to run git submodule update --init --recursive before building Build using ./docker_build_lib.sh script. Output library and header files will be available in Vitro-SDK-Lib directory.

Library info

If you've made manual changes to the sdk code and compiled it, but aren't seeing your changes, try to copy the compiled product like this:

• first copy the two files, libvitro-shard-sdkx.y.z.a and shard-sdk.h to your desired location.
• then, instead of copying the Vitro-SDK-Lib/vitroio-sdk folder, copy the vitroio-sdk folder directly from the vitro-shard-sdk repo.

Using

Copy static library and header files from Vitro-SDK-Lib to directory with source code of your project.

Known issues

‍NOTE: There is a few differences in SDK older than 2.0.0. Change branch to

see old guides

• To compile properly, application should be builded with mbed taken from commit #54e8693ef4ff7e025018094f290a1d5cf380941f (mbedOS release 6.16)
• When including files to your application, mbed.h has to be included before shard-sdk.h.

• User application should contain object of type BufferedSerial named pc and console override handler defined simmiliar to this:

  #define SERIAL_BAUDRATE 115200
  BufferedSerial pc(UART_DEBUG_TX, UART_DEBUG_RX, SERIAL_BAUDRATE);
   
  FileHandle *mbed::mbed_override_console(int fd)
  {
     return &pc;
  }

This serial port is used for application console.

Releasing SDK

To release the SDK from private repo to the public - take the following steps:

1. Introduce the changes to CHANGELOG.md in the private repository.

‍Warning!! Make sure no sensitive information is provided in the release notes or changelog. These changes will be copied over to public CHANGELOG.md repo.

1. Create a temp release branch and commit your changes (private repository)
2. Push your changes (private repository)

   ‍Remeber to update SDK verison here

   4. Merge to master (private repository)
3. Checkout locally on the origin/master and pull changes including merge commit (private repository)
4. Place a tag on the merge commit (private repository)
5. Push the tag with:

git push origin --tags

Pushing the tag will trigger the CI/CD pipeline.

The pipeline will compile the library, generate docs and push the changes to public repository on cicd-from-private branch.

1. Go to public repo on github checkout on cicd-from-private branch.
2. Create pull request, review changes and merge.