Adding sensors or components to the catalog¶
Description¶
This action allows the provider to register one or more sensors / components in the catalog.
http://<your_api_server.com>/catalog/<provider_id>
Formats | json |
Method | POST |
Permission | Writing |
Returns | No output data |
Parameters¶
Key | Description | Optional |
---|---|---|
sensor | Sensor ID to register | No |
description | Sensor description | Yes |
type | Sensor type | No |
dataType | Sensor data types | Yes |
unit | Unit of measure | Yes |
component | Component identifier to which the sensor belongs | Yes |
componentType | Component type | Yes |
componentDesc | Component description | Yes |
location | Location/s of the component to which the sensor is | Yes |
timeZone | TimeZone used by sensor observations when it is different to UTC | Yes |
publicAccess | Visualization check for the sensor in the public zone | Yes |
componentPublicAccess | Visualization check for the component in the public zone | Yes |
additionalInfo | Additional params related to the sensor | Yes |
componentAdditionalInfo | Additional params related to the component | Yes |
technicalDetails | Technical params related to the sensor | Yes |
componentTechnicalDetails | Technical params related to the component | Yes |
ttl | Time in minutes when sensor data will expire. If not set, the value of redis.expire.data.seconds will be applied. |
Yes |
state | State of the sensor, either online or offline |
Yes |
Please, note the following observations:
- The state and substate of a sensor cannot be changed via te API, only from the catalog. The default value for state is ‘online’, default value for substate is empty.
- The identifier must identify an univocal sensor provider, e.g., 2 sensors of the same provider may not have the same ID.
- The identifier must have only alphanumeric (i.e.letters and numbers), undescores and hyphens characters, with no embedded spaces.
- The list of sensor’s types are configured in the platform through the catalog web app. If you need a new one, it must be added using the administration.
- The possible values for the data type of the sensor is also defined in the platform configuration. The possible values are: number, text or boolean. The default value is number.
- If the attribute component is not passed as a parameter, the platform itself will create a catalog component with the same name as the sensor (if it does not already exist).
- If the attribute componentType is not reported and the component does not already exists in the system, the component will be defined as a generic component type.
- If the location attribute is not reported, the component is defined as a mobile type (with no fixed location). Otherwise it will be defined as static and set its location with the coordinates provided. If the element has several locations they should be informed separated by comma character.
- If the attribute type and / or componentType values are not configured in the catalog, the system will return a 400 error indicating that the parameters received are invalid .
- publicAccess param refers to the sensor’s visibility in the sensor’s public page. Default value is false.
- componentPublicAccess param refers to the components’s visibility in the public map. Default value is false.
- additionalInfo param is a <key,value> map that allows to store additional sensor information not mapped to any specific parameter. The information of this data map must not follow any internal rule.
- componentAdditionalInfo param is a <key,value> map that allows to store additional component not mapped to any specific parameter. The information of this data map must not follow any internal rule.
- technicalDetails parameter is a <key,value> map that allows to store additional sensor information. The available keys and their possible values are:
Description | Key | Values |
---|---|---|
Producer | producer | not restricted |
Model | model | not restricted |
Serial number | serialNumber | not restricted |
Energy | energy | 220VAC (electric network), 12_24_VDC (PoE), 185_230_V (lighting network), AUT_BAT (battery), SOLAR_BAT (solar battery) |
Response data¶
This action doesn’t return additional data beyond the HTTP status code associated with each request to the platform.
Examples¶
Adding one sensor¶
If you want to register a new humidity sensor with RE0025 identifier associated with the component whose identifier is METEO-1 of rec provider, the request to do will be the following:
http://<your_api_server.com>/catalog/rec
and in the body message:
{"sensors":[
{"sensor":"RE0025",
"description":"sensor 25 of moisture",
"type":"humidity",
"dataType":"number",
"unit":"%",
"component":"METEO-1",
"componentType":"meteo",
"componentDesc":"Test componente",
"location":"41.39479 2.148768",
"timeZone":"CET"
}
]}
This request will register a new sensor with name METEO_HUM-1 in the system of humidity type . Additionally, this sensor will be associated with the component METEO-1. If the component does not exist in the system yet , will be registered with the properties defined in the request (componentType, componentDesc and location).
Adding several sensors¶
In case it is necessary to add a set of sensors, the request will be very similar to the previous one, modifying the message body:
http://<your_api_server.com>/catalog/rec
in the body message
{"sensors":[
{"sensor":"tt01_REC013",
"description":"sensor12",
"type":"humidity",
"dataType":"number",
"unit":"grams",
"component":"METEO-1",
"componentType":"meteo",
"location":"41.39479 2.148768"
},
{"sensor":"tt01_REC014",
"description":"sensor12",
"type":"humidity",
"dataType":"number",
"unit":"grams",
"component":"METEO-1",
"componentType":"estaciometeo",
"location":"41.39479 2.148768"
}
]}
In this case, instead of registering a single sensor, there will be added two new sensors associated with the component named METEO-1. If the component does not yet exist in the system, will be registered with the properties specified in the request (type and location).
Adding one sensor with additional info¶
If you want to register a new humidity sensor, as in the first example, but also need additional information for the sensor and its component, the request to do is the following:
http://<your_api_server.com>/catalog/rec
and in the body message:
{"sensors":[
{"sensor":"RE0025",
"description":"sensor 25 of moisture",
"type":"humidity",
"dataType":"number",
"unit":"%",
"component":"METEO-1",
"componentType":"meteo",
"componentDesc":"Test componente",
"publicAccess":"true",
"componentPublicAccess":"true",
"location":"41.39479 2.148768",
"additionalInfo":{"accuracy":"4.5%","voltage":"2.1-3.6"},
"componentAdditionalInfo":{"altitude":"525 m."}
}
]}
This request will register a new sensor with name METEO_HUM-1 in the system of humidity type, as in the first example, and stores with the sensor two new attributes: accuracy and voltage.