upm  1.5.0
Sensor/Actuator repository for libmraa (v1.8.0)
Writing sensor documentation

It is highly encouraged to provide at least some basic documentation for the sensors that you want to add to UPM:

We currently document our libraries in the following way:

When submitting a new driver, you will have to at least fill out the mandatory fields as described below.

The library JSON file

Let's use the BME280 class snippet from the bmp280.json file as an example:

1 {
2  "Library": "bmp280",
3  "Description": "Bosch Atmospheric Sensor Library",
4  "Sensor Class":
5  {
6  "BME280":
7  {
8  "Name": "Digital Humidity, Pressure, and Temperature Sensor",
9  "Description": "The BME280 is as combined digital humidity, pressure and temperature sensor based on proven sensing principles. The sensor module is housed in an extremely compact metal-lid LGA package with a footprint of only 2.5 * 2.5 mm2 with a height of 0.93 mm. Its small dimensions and its low power consumption allow the implementation in battery driven devices such as handsets, GPS modules or watches. The BME280 is register and performance compatible to the Bosch Sensortec BMP280 digital pressure sensor",
10  "Aliases": ["bme280", "Grove - Barometer Sensor(BME280)"],
11  "Categories": ["pressure", "humidity", "temperature"],
12  "Connections": ["gpio", "i2c", "spi"],
13  "Project Type": ["prototyping", "industrial"],
14  "Manufacturers": ["adafruit", "seeed", "bosch"],
15  "Examples":
16  {
17  "Java": ["BMP280_Example.java"],
18  "Python": ["bmp280.py"],
19  "Node.js": ["bmp280.js"],
20  "C++": ["bmp280.cxx"],
21  "C": ["bmp280.c"]
22  },
23  "Specifications":
24  {
25  "Vdd": {"unit": "v", "low" : 1.7, "high": 3.6},
26  "Ioff" : {"unit": "mA", "low" : 0.0, "high": 0.0},
27  "Iavg": {"unit": "mA", "low" : 1, "high": 2},
28  "Pressure Range": {"unit": "hpA", "low" : 300, "high": 1100},
29  "Temperature Range": {"unit": "C", "low" : -40, "high": 85}
30  },
31  "Platforms":
32  {
33  "Intel Joule Module":
34  {
35  "Notes": ["Requires pull-up resistors with carrier board"]
36  }
37  },
38  "Urls" :
39  {
40  "Product Pages": ["https://www.adafruit.com/products/2652"],
41  "Datasheets": ["https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-11.pdf"],
42  "Schematics": ["https://learn.adafruit.com/assets/26693"]
43  }
44  }
45  }
46 }

Mandatory fields:

For the library:

For the sensor classes:

Optional and customizable fields

As mentioned, accepted values for some of the fields are listed under the ../src/groups.md "groups.md" file. If needed, you can add new categories for your sensor library following the existing format.

JSON files are automatically checked for correctness and required fields on code submissions.

Please do not use copyrighted images with your sensors!

Images from Seeed, DFRobot, Sparkfun or Adafruit are permitted.

Doxygen tags

The library doxygen block

New libraries must have the "@brief", "@defgroup" and "@ingroup" tags in one block. This usually follows the namespace and it is common to have one sensor per library.

You should end up with something like this (disregard the "@verbatim" tags in your actual code):


 * @brief Short description for entire library
 * Optional longer description.
 * @defgroup <lib-name> libupm-<lib-name>
 * @ingroup <manufacturer> <connection> <category> (<kit>)
1 Use `<lib-name>` to name the library.
3 For "@ingroup" add the same values as in the sensor block for manufacturer,
4 category, connection type and kit. If you have multiple classes or sensors
5 per library, only use the "@ingroup" tags that are common for all of them.
7 Existing groups that can be used for the manufacturer, connection, category and
8 kit tags are found in the *src/groups.md* file.
10 #### The sensor doxygen block
12 This is added just before the class declaration in your header(.hpp) file and has
13 one mandatory field. For single sensor libraries, this block will actually follow
14 immediately after the library block. If you have multiple sensor classes, add
15 this to every one.
17 Here's an example:
 * @library <lib-name>
 * @brief Short class/sensor description
 *   Then add a longer
 *   description here.


When adding to an existing library, <lib-name> needs to match that library's "@defgroup".

For more examples take a look at the existing headers in our github repository. Also, make sure to check our sensortemplate as it can facilitate new sensor additions.

Existing header files might have additional fields under the sensor block. These have been used in the past to generate sensor pages outside of doxygen, but they are now deprecated and not required for new additions.