How to write Sensor drivers - shunyaos/shunyainterfaces GitHub Wiki

Porting Sensors

This guide is a step-by-step tutorial on porting sensors.

Workflow

sensor-porting-workflow

Write code for Sensors

The flow for writing code is

  1. Setup Development Env (Install Shunya OS)
  2. Clone Shunya Interfaces
  3. Write Code
  4. Write Examples
  5. Document the API's

Before you begin Checklist

  • Ensure that the Sensor that you are porting has an issue on github.

Note: Issues help us track the phase of the feature. If the issue is missing then, Please create one.

Pre-requisites

  1. IoT Dev Board (Raspberry Pi 3/4 preferred)
  2. microSD card and microSD card Reader/Adapter
  3. Chosen Hardware Sensor (optional)

Step 1: Install Shunya OS.

Download and Install Shunya OS, follow this guide if you have any problems installing Shunya OS.

Boot into Shunya Interfaces and you are ready to test!.

This Step is required because we dont have instructions for cross-compilation. We will add cross-compilation in the near future. Please bear with us.

Step 2: Fork & Clone Shunya Interfaces

Fork shunya interfaces into your own Github account.

Running these commands below on the Terminal in Shunya OS, should get you the latest source.

# Clone the project, Skip if you have cloned the project.
git clone https://github.com/shunyaos/shunyainterfaces.git
cd shunyainterfaces

Create a new branch

Please create a new branch for the feature or sensor that you will be adding.

Branch Naming: Add Pre-fix feat- for every feature and feat-sensor- for every sensor that you are adding.

For Example:

  • feat-AWS-MQTT-support
  • feat-sensor-BME280

Running these commands on the terminal should do the trick.

git checkout develop
git checkout -b <branch-name>

Start Writing code

Writing code for sensors is easy but tedious task.

Before you begin, Please read the Guidelines.

Step 1 : Search for existing libraries.

Most of the sensors used are already ported to other libraries and hardly anyone writes the sensor code from scratch.

  • Best case scenario you find a library for Wiring Pi,
  • Next best case is you find a library for Arduino and
  • Worst case scenario is you don't find any code examples of the sensor.

Step 2 : Divide the library into blocks

All the sensor code can be divided into 3 blocks:

  1. Sensor Initialization.
  2. Sensor Configuration.
  3. Reading Raw data from the sensor.
  4. Calculating sensor value from the raw data.

Initialization

This is mostly Interfaces initialization.

Configuration

For sensors with built-in registers the configuration may contain

  1. Writing registers with initial/default values to make them ready for reading data.
  2. Configuring sensor parameters like Accuracy, resolution, data-rate, speed and many more.

Reading the data from the sensor

Typically consists of reading data from the memory inside the sensors. This needs 2 parameters, where to read from ? (the memory address) and How much bits/bytes to read from ? (typically the length of data to be read)

Converting the RAW data from the sensor to human readable format

Typically contains these points

  1. Re-arrangement of data (Shifting of MSB and LSB) if the data is more than 1 byte or 8 bits.
  2. Calculating the actual sensor value from the RAW data using math equations.

Step 3 : Write code for the blocks

Writing pseudo code before writing actual code is recommended.

The Sensor code needs to be written in Blocks

  1. Setup Block
  2. Data Block

Setup Block

The pseudo code written by the previous process needs to be converted into the actual Shunya Interfaces code.

Data Block

The pseudo code written by the previous process needs to be converted into the actual Shunya Interfaces code.

s

Step 4: Write Examples

After you finish writing the code Please write examples and put it in the examples/ folder.

Checklist

  • Write examples that use the API's for the feature/sensor that you have added.
  • Make sure that you have separate examples for Simple API's and Advance API's.
  • Ensure that your Example compiles with the library.

Step 5: Document

Document all the new API's and the sensor ID's that you have added.

Documentation should be in Markdown format and should be put into /docs/docs directory. (think this through)

Checklist

  • Make sure you have documented the Sensor ID.
  • Ensure Simple API's and Advance API's are documented.

Final Checklist

Before you submit a Pull Request, Please check the Checklist.

  • Ensure Sensor ID's are assigned, check by doing a diff for include/sensor_ids.h file.
  • Ensure the Sensor code is present in the peripherals/ folder
  • Ensure Simple API's and Advance API's are written in the include/simple_functions.h & include/adv_functions.h

When you do a diff you should basically see these changes in the file.