alexey.zholtikov/upm
1
0
Fork 0
mirror of https://github.com/eclipse/upm.git synced 2025-03-15 04:57:30 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

documentation.md: updated to explain the new JSON format for sensors

Browse Source 
Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>
This commit is contained in:
Mihai Tudor Panu 2017-04-20 16:53:18 -07:00
parent 5228df9a8b
commit ab841ef591
1 changed files with 105 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
docs/documentation.md
View File

@ -10,93 +10,96 @@ sensors that you want to add to UPM:
- Have the specific sensor manufacturer/model & version that you used, if you - Have the specific sensor manufacturer/model & version that you used, if you
support multiple versions please list. support multiple versions please list.
- Simple comments do not need full stops. - Simple comments do not need full stops.
- Stick to <80 chars per line even in comments. - Stick to <80 chars per line where possible.
- No text is allowed on the same line as the start or end of a comment /** */. - No text is allowed on the same line as the start or end of a comment /** */.
####The sensor block We currently document our libraries in the following way:
This is added just before the class declaration in your header(.h) file and has * **Doxygen** is used for documenting the API and generating the categories on
mandatory fields. For single sensor libraries, this block will actually the [UPM Libraries page](https://iotdk.intel.com/docs/master/upm/modules.html).
follow immediately after the library block. If you have multiple physical You can learn more about the Doxygen syntax [here](http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html).
sensors, add this to every one. * **JSON** is used to provide sensor specifications, descriptions, supported
Here's an example (disregard the "@verbatim" tags in your actual code): platforms, links and many more.
``` When submitting a new driver, you will have to at least fill out the mandatory
@verbatim fields as described below.
/**
* @library <lib-name> ### The library JSON file
* @sensor <chip-id>
* @comname <component-name> Let's use the bme280.json file for the BME280 sensor as an example:
* @altname <alt-name>
* @altid <alt-id> ```json
* @type <component-category> {
* @man <component-manufacturer> "library": "bmp280",
* @web <component-weblinks> "description": "Bosch Atmospheric Sensor Library",
* @con <connection-type> "classes":
* @kit <component-kit> {
* "BME280":
* @brief Short class/sensor description {
* "names": ["Digital Humidity, Pressure, and Temperature Sensor", "Grove Temp&Humi&Barometer Sensor", "BME280"],
* Then add a longer "categories": ["pressure", "humidity", "temperature"],
* description here. "connections": ["gpio", "i2c", "spi"],
* "manufacturers": ["adafruit", "seeed"],
* @image html <component-img.jpeg> "kits": [],
* @snippet <example-name.cxx> Interesting "images": ["bme280.jpeg"],
*/ "examples": ["bmp280-bme280.c", "bmp280-bme280.cxx", "BME280_Example.java", "bme280.js", , "bme280.py"],
@endverbatim "usage": ["prototype", "product"],
"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",
"specifications":
{
"vdd": {"low": "1.7V", "high": "3.6V"},
"ioff" : {"low": "0.0A", "high": "0.0A"},
"iavg": {"low": "0.1uA", "high": "0.1uA"},
"Pressure range" : "300...1100 hPa",
"Temperature range" : "-40...85°C"
},
"platforms":
{
"Intel Joule Module":
{
"notes": ["Requires pull-up resistors with carrier board"],
"images": [""]
}
},
"urls" :
{
"products": ["https://www.adafruit.com/products/2652", "https://www.seeedstudio.com/Grove-Temp%26Humi%26Barometer-Sensor-%28BME280%29-p-2653.html"],
"datasheets": ["https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-11.pdf"],
"schematics": ["https://learn.adafruit.com/assets/26693"]
}
}
}
}
``` ```
- `<lib-name>` When adding to an existing library this needs to match that **Mandatory fields:**
library's "@defgroup", otherwise this is a new library name, generally the - `names` Title Case descriptive names for your sensor. Multiple values can be
same as chip id. *Mandatory* used to capture the chip name, generic name, or specific name for a vendor.
- `<chip-id>` Usually the chip number used by the sensor. When this is not Examples: Digital Pressure Sensor, Serial MP3 Module,
available or relevant, use a unique descriptor that makes sense. Must match - `categories` Mention one or more categories the sensor fits in. Accepted
class name. *Mandatory* values are listed in the groups.md file.
- `<component-name>` Title Case descriptive name for your sensor, try to avoid - `connections` Specifies how does the sensor connect to the board. Accepted
including the manufacturer's name here. Examples: Digital Pressure Sensor, values are listed in the groups.md file.
Serial MP3 Module, etc... *Mandatory* - `manufacturers` List of sensor manufacturers or vendors. Can be 'generic',
- `<alt-name>` Alternative names that your sensor driver might have. This may other accepted values in groups.md.
include manufacturer's name. *Optional*
- `<alt-id>` Alternative chip-ids that your sensor driver supports. *Optional*
- `<component-category>` Mention one or more categories the sensor fits in. Can
be 'other'. *Mandatory*
- `<component-manufacturer>` Sensor manufacturer. Can be 'generic'. *Mandatory*
- `<component-weblinks>` Links to vendors or data-sheets. *Optional*
- `<connection-type>` Specifies how does the sensor connect to the board
*Mandatory*
- `<component-kit>` Specifies if the sensor is part of a kit. *Optional*
Existing groups that can be used for the manufacturer, connection, category and **Optional and customizable fields**
kit tags are found in the *src/groups.md* file. - `kits` Specifies if the sensor is part of a kit.
Optionally, a small representative image can be placed in the "docs/images" **Please do not use copyrighted images with your sensors!**
subfolder and linked with the "@image" tag.
**Please do not use existing, copyrighted images with your sensors!**
The example should have an 'Interesting' section which will be highlighted as Images from Seeed, DFRobot, Sparkfun or Adafruit are permitted.
a code sample in doxygen. Everything in between such tags will show up in the
class documentation when "@snippet" is added at the end of a class docstring.
Tags use this format (in "example-name.cxx"):
``` ### Doxygen tags
@verbatim
//! [Interesting]
...example code here... #### The library doxygen block
//! [Interesting]
@endverbatim
```
For more examples take a look at the existing headers in our github repository.
####The library block
New libraries must have the "@brief", "@defgroup" and "@ingroup" tags in one 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 block. This usually follows the namespace and it is common to have one sensor
per library. per library.
You should end up with something like this: You should end up with something like this (disregard the "@verbatim" tags in
your actual code):
``` ```
@verbatim @verbatim
@ -111,8 +114,37 @@ You should end up with something like this:
@endverbatim @endverbatim
``` ```
In "@defgroup" use the same `<lib-name>` used in the sensor block. Multiple Use `<lib-name>` to name the library.
sensors can be added to the same library this way.
For "@ingroup" add the same values as in the sensor block for manufacturer, For "@ingroup" add the same values as in the sensor block for manufacturer,
category, connection type and kit. If you have multiple classes or sensors category, connection type and kit. If you have multiple classes or sensors
per library, only use the "@ingroup" tags that are common for all of them. per library, only use the "@ingroup" tags that are common for all of them.
Existing groups that can be used for the manufacturer, connection, category and
kit tags are found in the *src/groups.md* file.
#### The sensor doxygen block
This is added just before the class declaration in your header(.hpp) file and has
one mandatory field. For single sensor libraries, this block will actually follow
immediately after the library block. If you have multiple sensor classes, add
this to every one.
Here's an example:
```
@verbatim
/**
* @library <lib-name>
* @brief Short class/sensor description
*
* Then add a longer
* description here.
*/
@endverbatim
```
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.