alexey.zholtikov/upm
1
0
Fork 0
mirror of https://github.com/eclipse/upm.git synced 2025-03-14 20:47: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
support multiple versions please list.
- 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 /** */.
####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
mandatory fields. For single sensor libraries, this block will actually
follow immediately after the library block. If you have multiple physical
sensors, add this to every one.
Here's an example (disregard the "@verbatim" tags in your actual code):
* **Doxygen** is used for documenting the API and generating the categories on
the [UPM Libraries page](https://iotdk.intel.com/docs/master/upm/modules.html).
You can learn more about the Doxygen syntax [here](http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html).
* **JSON** is used to provide sensor specifications, descriptions, supported
platforms, links and many more.
```
@verbatim
/**
* @library <lib-name>
* @sensor <chip-id>
* @comname <component-name>
* @altname <alt-name>
* @altid <alt-id>
* @type <component-category>
* @man <component-manufacturer>
* @web <component-weblinks>
* @con <connection-type>
* @kit <component-kit>
*
* @brief Short class/sensor description
*
* Then add a longer
* description here.
*
* @image html <component-img.jpeg>
* @snippet <example-name.cxx> Interesting
*/
@endverbatim
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.json file for the BME280 sensor as an example:
```json
{
"library": "bmp280",
"description": "Bosch Atmospheric Sensor Library",
"classes":
{
"BME280":
{
"names": ["Digital Humidity, Pressure, and Temperature Sensor", "Grove Temp&Humi&Barometer Sensor", "BME280"],
"categories": ["pressure", "humidity", "temperature"],
"connections": ["gpio", "i2c", "spi"],
"manufacturers": ["adafruit", "seeed"],
"kits": [],
"images": ["bme280.jpeg"],
"examples": ["bmp280-bme280.c", "bmp280-bme280.cxx", "BME280_Example.java", "bme280.js", , "bme280.py"],
"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
library's "@defgroup", otherwise this is a new library name, generally the
same as chip id. *Mandatory*
- `<chip-id>` Usually the chip number used by the sensor. When this is not
available or relevant, use a unique descriptor that makes sense. Must match
class name. *Mandatory*
- `<component-name>` Title Case descriptive name for your sensor, try to avoid
including the manufacturer's name here. Examples: Digital Pressure Sensor,
Serial MP3 Module, etc... *Mandatory*
- `<alt-name>` Alternative names that your sensor driver might have. This may
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*
**Mandatory fields:**
- `names` Title Case descriptive names for your sensor. Multiple values can be
used to capture the chip name, generic name, or specific name for a vendor.
Examples: Digital Pressure Sensor, Serial MP3 Module,
- `categories` Mention one or more categories the sensor fits in. Accepted
values are listed in the groups.md file.
- `connections` Specifies how does the sensor connect to the board. Accepted
values are listed in the groups.md file.
- `manufacturers` List of sensor manufacturers or vendors. Can be 'generic',
other accepted values in groups.md.
Existing groups that can be used for the manufacturer, connection, category and
kit tags are found in the *src/groups.md* file.
**Optional and customizable fields**
- `kits` Specifies if the sensor is part of a kit.
Optionally, a small representative image can be placed in the "docs/images"
subfolder and linked with the "@image" tag.
**Please do not use existing, copyrighted images with your sensors!**
**Please do not use copyrighted images with your sensors!**
The example should have an 'Interesting' section which will be highlighted as
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"):
Images from Seeed, DFRobot, Sparkfun or Adafruit are permitted.
```
@verbatim
//! [Interesting]
### Doxygen tags
...example code here...
//! [Interesting]
@endverbatim
```
For more examples take a look at the existing headers in our github repository.
####The library block
#### 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:
You should end up with something like this (disregard the "@verbatim" tags in
your actual code):
```
@verbatim
@ -111,8 +114,37 @@ You should end up with something like this:
@endverbatim
```
In "@defgroup" use the same `<lib-name>` used in the sensor block. Multiple
sensors can be added to the same library this way.
Use `<lib-name>` to name the library.
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
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.