Commands and settings

Preparing an HTTP request

Limitations

The sensor entails a small HTTP server used for setting parameters, performing some actions and command and occasionnaly retrieving data.

Its server has the priority over measuring in order to ensure a quick response time. Threefore, HTTP requests to the sensor should be limited in time. Making a burst of a dozen request for setup is totally aceptable. Setting the LED color and intensity from time to time is also not a problem. However, requesting data every ten seconds or changing the light color every seconds will almost stop the measurement processes.

Data are best obtained through MQTT or InfluxDB storage. The sensor then manages the best time of access without inhibiting its operations.

MD5 secret phrase

The MD5 secret phrase ensures that the sole owner of the sensor may access its data and change its parameters. The security principles around the sensors are described here. This describes the generation of the MD5 secret phrase. Read the section The MD5 secret phrase to get all the informations related to it.

IP address

Before accessing the sensor, you will need to find its IP address on the network. This is best done by looking at the DHCP tables of your WiFi router. Beyond, if you’d wanted to scan for modules on the network, a good practice is to perform a simple GET request at any possible IP address. Most of the time, this will issue a timeout. If the IP address answers, and if this is a sensor, a JSON payload will be returned with its identity information. This command is described in the next section.

Discovering sensors on the network

When discovering sensors on the network, a simple GET request at its IP address returns a short information payload about the sensor.

URL: http://<ip address>
URL: https://<ip address>
Method: GET
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "type": "Ambient16",
        "version": "d07e9e98y",
        "udid": "3c71bfb38278",
        "deviceType": "3c71",
        "token": "uulroqkt"
}

Settings

Location

Sets the origin name and type, describing where the sensor is placed in the house. The location type is important as it can be used later for adapting the A.I. to specific environments. For instance, if you want to activate the shower detection then the type should be bathroom.

Location – or origins – are referred to by a Unique Origin ID, or UOID. When using the DESCAMPS.TECHNOLOGY App during the sensor pairing phase, a UOID is provided. Our clound ensures that this UOID is indeed unique among all your sensors. However, you are perfectly free to setup your own UOID. You are then responsible for their unicity. UOID are used by InfluxDB and in MQTT messages for telling where measurements are originated.

URL: http://<ip address>/settings
URL: https://<ip address>/settings
Method: POST
Mode: SSL or unencrypted
Return: current settings list
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "origin": {
                "uoid": "<UOID>",
                "name": "<string>",
                "type": "<room type code>"
        }
}

Room types codes

Room type

Code

unknown

0

outdoor

1

bedroom

2

kitchen

3

livingRoom

4

bathroom

5

entrance

6

toilets

7

garage

8

corridor

9

fridge

10

washer

11

dryer

12

dishwasher

13

tvSet

14

oven

15

hotplate

16

home

17

office

18

veranda

19

basement

20

utilityroom

21

Time

Sets the present time of the sensor in the form of a unix timestamp. Although the absolute time is not needed for the module to perform most its basic tasks, time is used for computing some parameters like the Sun position. Besides, the sensor will get the present time from NTP servers of the internet. So unless you have disabled the NTP function, you are not equired to set the time of the sensor.

URL: http://<ip address>/settings
URL: https://<ip address>/settings
Method: POST
Mode: SSL or unencrypted
Return: current settings list
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "time": {
                "timestamp": "<number>"
        }
}

Event levels

Some events need levels to be triggered. For instance, three temperature events can be enabled – under range, in range, over the range – requiring an upper and a lower value. Use this call to set up these level values.

When sending a non numerical value as lower or upper range, the value will be ignored and the previous value will be kept. No specific error core is returned. Also, it is the responsibility of the user to ensure that the upper level is greater than the lower level. Not doing so will affect the events detection logic.

URL: http://<ip address>/settings
URL: https://<ip address>/settings
Method: POST
Mode: SSL or unencrypted
Return: current settings list
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "ranges": {
                "co2LowerRange":"<number>",
                "co2UpperRange":"<number>",
                "humidityLowerRange":"<number>",
                "humidityUpperRange":"<number>",
                "temperatureLowerRange":"<number>",
                "temperatureUpperRange":"<number>",
                "soundLowerRange":"<number>",
                "soundUpperRange":"<number>",
                "lightIntensityLowerRange":"<number>",
                "lightIntensityUpperRange":"<number>",
                "outdoorTemperatureLowerRange":"<number>",
                "outdoorTemperatureUpperRange":"<number>",
                "airPressureLowerRange":"<number>",
                "airPressureUpperRange":"<number>",
                "vibrationLevel":"<number>"
        }
}

Events

The sensors can trigger event besides storing a regular flux of data. These events are sent to an MQTT broker in your own infrastructure of to the DESCAMPS.TECHNOLOGY cloud. Besides, events may also be reported by the sensor LED. Using the following command sets the result of an specific event which codes are listed below. (Note that not all events are implemented today but should be released in the future. This explains why event codes have gaps or not in the increasing order.).

LED color names are those used for LED commands as described here.

URL: http://<ip address>/settings
URL: https://<ip address>/settings
Method: POST
Mode: SSL or unencrypted
Return: current settings list
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "event": {
                "eventId": "<code>",
                "mqttReporting":"<boolean>",
                "ledColorName":"<colorCode>",
                "duration":"<number>"
        }
}

Event codes

physical parameter

description

code

co2

sudden change

0

co2

enters range

1

co2

over range

2

co2

below range

3

humidity

sudden change

4

humidity

enters range

5

humidity

over range

6

humidity

below range

7

temperature

sudden change

13

temperature

enters range

14

temperature

over range

15

temperature

below range

16

airpressure

enters range

21

airpressure

over range

22

airpressure

below range

23

sound

sudden change

24

sound

silence detected

25

sound

noise detected

26

sound

enters range

27

sound

over range

28

sound

below range

29

light

lights on

37

light

lights off

38

light

sunlight detected

40

light

moonlight detected

41

light

direct sunLight detected

42

light

darkness detected

43

light intensity

enters range

44

light intensity

over range

45

light intensity

below range

46

light

artificial light detected

47

light

natural light

48

accelerometer

tap

54

accelerometer

double tap

55

accelerometer

sensor moved

56

accelerometer

attitude change detected

57

accelerometer

sensor motion over threshold

65

outdoor temperature

enters range

58

outdoor temperature

over range

59

outdoor temperature

below range

60

motion

starts

63

motion

stops

64

Return of settings request

When issuing a setting request, the sensor will return a JSON payload containing all the present settings. In SSL mode, the payload contains confidential parameters like the WiFi password (ass shown next). These information are securerly encoded between the sensor and your application. However, in non-SSL mode, these data are not encrypted and could be intercepted. Hence, only non sensitive parameters will be returned.

JSON payload
{
        "positionIsDefined": false,
        "altitudeIsDefined": false,
        "positionAutoIsDefined": false,
        "altitudeAutoIsDefined": false,
        "moonPositionIsDefined": false,
        "influxIsDefined": false,
        "defaultDatabaseEnabled": true,
        "mqttIsDefined": false,
        "defaultMQTTEnabled": true,
        "ntpServer": "",
        "ntpEnabled": false,
        "ntpDefaultEnabled": true,
        "isInternetConnected": true,
        "isNetworkConnected": true,
        "udid": "3c71bfb38278",
        "wifiError": 0,
        "mqttError": 0,
        "otaError": 0,
        "ssid": "myHomeWifiSSID",
        "password": "myHomeWifiPassword",
        "outdoorTemperatureIsDefined": false,
        "isRealTime": true,
        "timestamp": 586,
        "uoidIsDefined": true,
        "uoid": "0000",
        "originName": "my room",
        "originType": 0,
        "events": [
                [36, true, "off", 0],
                [54, true, "orange", 3],
                [55, true, "purple", 3],
                [57, true, "off", 0],
                [63, true, "off", 0],
                [64, true, "off", 0]
        ],
        "cloudStorageEnabled": false,
        "temperatureLowerRange": 20.00,
        "temperatureUpperRange": 31.00,
        "co2LowerRange": 600.00,
        "co2UpperRange": 1500.00,
        "humidityLowerRange": 30.00,
        "humidityUpperRange": 60.00,
        "lightIntensityLowerRange": 70.00,
        "lightIntensityUpperRange": 150.00,
        "soundLowerRange": 60.00,
        "soundUpperRange": 70.00,
        "outdoorTemperatureLowerRange": -20.00,
        "outdoorTemperatureUpperRange": 40.00,
        "airPressureLowerRange": 1016.00,
        "airPressureUpperRange": 1022.00,
        "vibrationLevel": 400,
        "version": "d22c2f90",
        "token": "bov4wbF5"
}

Commands

Reset

Clears the settings and the learned parameters

URL: http://<ip address>/command
URL: https://<ip address>/command
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "command": "reset"
}

Factory reset

Clears the settings and the learned routines. Application updates are erased. The ownership of the module is cleared. The sensor is ready to be paired.

URL: http://<ip address>/command
URL: https://<ip address>/command
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "command": "factoryReset"
}

Reboot

Reboots the module

URL: http://<ip address>/command
URL: https://<ip address>/command
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "command": "reboot"
}

Update app

Updates the sensor software from the DESCAMPS.TECHNOLOGY cloud if necessary.

URL: http://<ip address>/command
URL: https://<ip address>/command
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "command": "updateApp"
}

Status

Returns the settings and status of the module.

URL: http://<ip address>/command
URL: https://<ip address>/command
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "command": "status"
}

Switching between SSL and non encrypted mode

For some operations, like reading the sensor full configuration (indluding your passwords), the sensor needs to be switched in SSL mode. Most of the time, this is not required. Using this command makes the switch. When the SSL mode is activated, the sensor will stop sending MQTT and InfluxDB data. This can only be used for bery short periods of time.

URL: http://<ip address>/command
URL: https://<ip address>/command
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "command": "setServer",
        "ssl":"<boolean>"
}

LED commands

LED control with color codes

Sets the color of the LED. Each color corresponds to a color code. The duration is set in seconds. When setting the duration to 0, the LED will be on indefinitely. The duration cannot be shorter than a second.

URL: http://<ip address>/light
URL: https://<ip address>/light
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "setColor": {
                "ledColorName":"<colorCode>",
                "duration":"<number>"
        }
}

Code

Color

off

switches off the LED

red

red

blinkingRed

blinking red

green

green

blinkingGreen

blinking green

blue

blue

blinkingBlue

blinking blue

yellow

yellow

blinkingYellow

blinking yellow

purple

purple

blinkingPurple

blinking purple

cyan

cyan

blinkingCyan

blinking cyan

orange

orange

blinkingOrange

blinking orange

white

white

blinkingWhite

blinking white

LED control with RGB values

Sets the color of the LED according to Red/Green/Blue values between 0 and 1.

URL: http://<ip address>/light
URL: https://<ip address>/light
Method: POST
Mode: SSL or unencrypted
Return: status JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "setColor": {
                "red":"<number>",
                "green":"<number>",
                "blue":"<number>",
                "blinking":"<boolean>",
                "duration":"<number>"
        }
}

Retrieving data

Getting data

Reteiving data though HTTP request from the sensor is only meant for debugging purposes or very occasional accesses. Indeed, the sensor gives priority to incoming HTTP requests and so ensures a quick reply time. However, this might slow down or stop the measurement sequence of the sensor. A single access is not a problem. However, polling data every 10 seconds would totally stop the measurement sequence.

Data can be retrieved in their minimal or standard form. The minimal data payload only provides the essential values.

URL: http://<ip address>/data
URL: https://<ip address>/data
Method: POST
Mode: SSL or unencrypted
Return: data JSON payload
JSON payload
{
        "udid": "<module udid>",
        "secret": "<md5 secret phrase>",
        "kind":"<minimal/standard>"
}

Minimal data payload example JSON

JSON payload
{
        "accelerometer_motionQuantity": 0.000000,
        "light_powerSpectrum5Hz": 18.721977,
        "temperature_rawValue": 28.602274,
        "humidity_rawValue": 42.232395,
        "co2_rawValue": 0.997918,
        "light_redRawValue": 77.222931,
        "light_greenRawValue": 93.127388,
        "light_blueRawValue": 74.248405,
        "light_intensityRawValue": 161.898087,
        "light_temperature": 17592.253906,
        "motion_motionQuantity": 0.000000,
        "sound_rawValue": 799.893982,
        "accelerometer_deviceAttitude": 5,
        "accelerometer_deviceTap": 0,
        "motion_type": 1,
        "motion_speed": 0,
        "motion_direction": 0,
        "motion_distance": 0,
        "time": 1581324777
}

Standard data payload example JSON

JSON payload
{
        "accelerometer_motionQuantity": 0.000000,
        "temperature_casing": 33.535416,
        "airpressure_calibratedValueSeaLevel": 1015.802979,
        "light_powerSpectrum5Hz": 13.161825,
        "temperature_rawValue": 28.602274,
        "temperature_calibratedValue_celcius": 0.000000,
        "temperature_trend": 0.000000,
        "humidity_rawValue": 42.502480,
        "humidity_calibratedValue": 0.000000,
        "humidity_trend": 0.000000,
        "dewpoint_calibratedValue": 15.3,
        "saturatingvapor_calibratedValue": 6.112100,
        "co2_rawValue": 0.997369,
        "co2_calibratedValue": 0.000000,
        "co2_trend": 0.000000,
        "light_redRawValue": 89.038216,
        "light_greenRawValue": 110.630569,
        "light_blueRawValue": 80.713379,
        "light_intensityRawValue": 183.388535,
        "light_intensity": 183.388535,
        "light_temperature": 14864.974609,
        "ephemeris_sunAltitude": -13881223910018697363609092096.000000,
        "ephemeris_sunAzimuth": -0.001309,
        "motion_motionQuantity": 0.000000,
        "motion_presenceProbability": 1.000000,
        "sound_rawValue": 802.558044,
        "sound_calibratedValue_dBA": 0.000000,
        "sound_calibratedValue_dBC": 0.000000,
        "sound_silenceQuality": 0.000000,
        "lightwaste_detected": 0.000000,
        "lightwaste_cumulatedMinutes": 0.000000,
        "lightwaste_cumulatedEnergy": 0.000000,
        "wellbeing_ppd": 61.311150,
        "wellbeing_pmv": 1.691781,
        "wellbeing_recommendedClothing": -1.000000,
        "wellbeing_recommendedTemperature": 18.815018,
        "wellbeing_predictiveClothing": 1.000000,
        "wellbeing_recommendedNightClothing": 0.038063,
        "wellbeing_recommendedBedroomTemperature": 16.000000,
        "temperature_outdoor": 999.000000,
        "accelerometer_deviceAttitude": 5,
        "accelerometer_deviceTap": 0,
        "motion_type": 0,
        "motion_speed": 0,
        "motion_direction": 0,
        "motion_distance": 0,
        "light_lightOnDetected": {
                "eventId": 37,
                "lastTimeOfOccurrence": 137,
                "duration": 125.532,
                "isOccurring": 1,
                "probability": 1
        },
        "light_lightOffDetected": {
                "eventId": 38,
                "lastTimeOfOccurrence": -1,
                "duration": 0,
                "isOccurring": 0,
                "probability": 0
        },
        "light_darknessDetected": {
                "eventId": 43,
                "lastTimeOfOccurrence": -1,
                "duration": 0,
                "isOccurring": 0,
                "probability": 0
        },
        "light_sunLightDetected": {
                "eventId": 40,
                "lastTimeOfOccurrence": -1,
                "duration": 0,
                "isOccurring": 0,
                "probability": -1
        },
        "light_artificialLight": {
                "eventId": 47,
                "lastTimeOfOccurrence": -1,
                "duration": 0,
                "isOccurring": 0,
                "probability": -1
        },
        "sound_silenceDetected": {
                "eventId": 25,
                "lastTimeOfOccurrence": -1,
                "duration": 0,
                "isOccurring": 0,
                "probability": 0
        },
        "sound_noiseDetected": {
                "eventId": 26,
                "lastTimeOfOccurrence": 137,
                "duration": 125.532,
                "isOccurring": 1,
                "probability": 1
        },
        "time": 1581324726
}