Milesight Thermostat Api

Description

The Milesight Thermostat API is an internal tool exclusively accessible to our backend team. It serves as a command hub for the Milesight WT201 thermostats using lorawan downlink commands. Additionally, the API allows facilitating effective control of their operational state.

Requirements

- RabbitMQ 3.9.11
- Node 20.15.0

Installation

``bash
$ npm install
`

Configuration

- AWS_ACCESS_KEY_ID
- AWS Access Key ID
- AWS_SECRET_ACCESS_KEY
- AWS Secret Key

- NODE_ENV
- Node environment
- LOG_LEVEL
- value can be debug, info, error and verbose.
- MILESIGHT_THERMOSTAT_API_PORT
- configurable host port and has a default of 9059

- AMQP_HOST
- rabbitmq host
- AMQP_USERNAME
- rabbitmq user
- AMQP_PASSWORD
- rabbitmq password
- AMQP_PORT
- rabbitmq port

Running the app

`bash


development

$ npm run start

watch mode

$ npm run start:dev

production mode

$ npm run start:prod
`

Test

`bash


unit tests

$ npm run test

e2e tests

$ npm run test:e2e

test coverage

$ npm run test:cov
`

REST API

$3

`
GET /thermostat/milesight
`

maxResult(optional) range from 1-250 (default is 25)

nextToken(optional) token for the succeeding page/request


$3

`
POST thermostat/milesight/mode

Body: {
deviceEui: string;
serialNumber?: string;
mode: 'Heat' | 'EMHeat' | 'Cool' | 'Auto';
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

mode(required) Mode of the HVAC unit


$3

`
POST thermostat/milesight/hold

Body: {
deviceEui: string;
serialNumber?: string;
mode: 'Heat' | 'EMHeat' | 'Cool' | 'Auto';
dualTargetTemperature?: boolean;
temperatureUnit?: 'F' | 'C'
coolingSetPoint?: number;
heatingSetPoint?: number;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

mode(required) mode of the HVAC unit

dualTargetTemperature (optional) true to enable dual target temperature mode of thermostat

temperatureUnit(optional) temperature unit for the device to use

coolingSetPoint(optional) target temperature for cooling

heatingSetPoint(optional) target temperature for heating


$3


`
POST thermostat/milesight/schedule

Body: {
deviceEui: string,
serialNumber?: string,
dualTargetTemperature?: boolean;
temperatureUnit?: string,
controlMode: string,
occupiedHoursFanMode: string,
unoccupiedHoursFanMode: string,
occupiedHeatSetPoint: number;
unoccupiedHeatSetPoint: number;
occupiedCoolSetPoint: number;
unoccupiedCoolSetPoint: number;
schedule: {
monday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
tuesday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
wednesday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
thursday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
friday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
saturday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
sunday: {
planEnable: boolean;
startTime: string;
endTime: string;
},
}
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

dualTargetTemperature (optional) true to enable dual target temperature mode of thermostat

temperatureUnit(optional) temperature unit 'F' for fahrenheight 'C' for celsius

controlMode(required) working mode of thermostat

schedule(required): schedule for each day

occupiedHoursFanMode fan mode during occupied hours ('Auto' | 'On' | 'Circulate')

unoccupiedHoursFanMode fan mode during unoccupied hours ('Auto' | 'On' | 'Circulate')

occupiedHeatSetPoint desired temperature during occupied hours

unoccupiedHeatSetPoint desired temperature during unoccupied hours

occupiedCoolSetPoint desired temperature during occupied hours

unoccupiedCoolSetPoint desired temperature during unoccupied hours


`

{
monday:
{
planEnable: boolean to enable the plan for Monday
startTime: string in 24-hour format (HH) to define start time
endTime: string in 24-hour format (HH) to define end time
}
tuesday: Same structure as monday
wednesday: Same structure as monday
thursday: Same structure as monday
friday: Same structure as monday
saturday: Same structure as monday
sunday: Same structure as monday
}
`




$3

`
POST thermostat/milesight/retrieve

Body: {
deviceEui: string;
serialNumber?: string;
startTime: ISO8601 string;
endTime: ISO8601 string;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

startTime(required) start time

endTime(required) end time


$3

`
POST thermostat/milesight/reboot

Body: {
deviceEui: string;
serialNumber?: string;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat


$3

`
POST thermostat/milesight/timezone

Body: {
deviceEui: string;
serialNumber?: string;
timezoneOffset: number;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

timezoneOffset(required) timezone range (-12, 14)


$3

`
POST thermostat/milesight/lock

Body: {
deviceEui: string;
serialNumber?: string;
powerButton: boolean;
temperatureUpButton: boolean;
temperatureDownButton: boolean;
fanButton: boolean;
modeButton: boolean;
resetButton: boolean;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

powerButton(required) true to lock and false to disable lock

temperatureUpButton(required) true to lock and false to disable lock

temperatureDownButton(required) true to lock and false to disable lock

fanButton(required) true to lock and false to disable lock

modeButton(required) true to lock and false to disable lock

resetButton(required) true to lock and false to disable lock


$3

`
POST thermostat/milesight/report-interval

Body: {
deviceEui: string;
serialNumber?: string;
reportInterval: number;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

reportInterval(required) report interval range (1, 1440)


$3

`
POST thermostat/milesight/fan-execute-time

Body: {
deviceEui: string;
serialNumber?: string;
time: number;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

time(required) fan execute time range (5, 55)


`
POST thermostat/milesight/fan-delay

Body: {
deviceEui: string;
serialNumber?: string;
enabled: boolean
time: number;
}
`
deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

enabled(required) true to enable and false to disable

time(required) fan delay time in minutes (1-59). Note: v1 hardware supports 5-55, v2 hardware supports 1-59


$3

`
POST /thermostat/milesight/heat-pump
Content-Type: application/json

{
"deviceEui": "A840418XXXXXX",
"serialNumber": "A840418XXXXXX",
"heatPump": true
}
`

deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

heatPump(required) true to combine and false to disable





$3

`
POST /thermostat/milesight/wires-relay
Content-Type: application/json

{
"deviceEui": "A840418XXXXXX",
"serialNumber": "A840418XXXXXX",
"y1": true,
"y2_gl": false,
"w1": true,
"w2_aux": false,
"e": true,
"g": false,
"ob": true
}

`

deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

y1(required) true to enable Y1 relay and false to disable

y2_gl(required) true to enable Y2/GL relay and false to disable

w1(required) true to enable W1 relay and false to disable

w2_aux(required) true to enable W2/AUX relay and false to disable

e(required) true to enable E relay and false to disable

g(required) true to enable G relay and false to disable

ob(required) true to enable OB relay and false to disable


$3

`
POST /thermostat/milesight/dst
Content-Type: application/json

{
"deviceEui": "A840418XXXXXX",
"serialNumber": "A840418XXXXXX",
"enabled": true,
"offset": 60,
"startMonth": "march",
"startWeek": 2,
"startWeekday": "sunday",
"startTime": "02:00",
"endMonth": "november",
"endWeek": 1,
"endWeekday": "sunday",
"endTime": "03:00"
}
`

deviceEui(required) device eui of the lorawan thermostat

serialNumber(optional) serial number of the lorawan thermostat

enabled(required) true to enable DST and false to disable

offset(required) DST offset in minutes (commonly 60 for 1 hour), range: -720 to 720

startMonth(required) Start month: january, february, march, april, may, june, july, august, september, october, november, december

startWeek(required) Start week number (1-5)

startWeekday(required) Start weekday: monday, tuesday, wednesday, thursday, friday, saturday, sunday

startTime(required) Start time in HH:mm format (24-hour, e.g., "02:00")

endMonth(required) End month: january, february, march, april, may, june, july, august, september, october, november, december

endWeek(required) End week number (1-5)

endWeekday(required) End weekday: monday, tuesday, wednesday, thursday, friday, saturday, sunday

endTime(required) End time in HH:mm format (24-hour, e.g., "03:00")


Encoding Functions that are not included on this API

The following functions are used internally by milesightDeviceEncoder():

| Function Name | Description |Sample |
|---------------|-------------|-------|
| reportStatus() | For querying some configurations of WT201
0-Query Schedule
1-Query Temperature Control Status
2-Query the target temperature and range for each mode.
|
`
{ "report_status": 1 }
`
| setCollectionInterval() | time interval at which the WT201 collects ambient temperature and humidity data. The LoRaWAN data reported by the WT201 is based on the data obtained from the most recent sampling interval (seconds) |
`
{ "collection_interval": 30 }
`
| syncTime() | Trigger time synchronization |
`
{ "sync_time": 1 }
`
| setTemperatureUnitDisplay() | Set display unit: 0 = Celsius, 1 = Fahrenheit. |
`
{ "temperature_unit": 0 }
`
| setSystemStatus() | Enable or disable the system. System refers to the entire thermostat, and "system off" means turning off the whole WT201 thermostat |
`
{ "system_status": 1 }
`
| setTemperatureCalibration() | Enable or disable the ambient temperature calibration function.
0-disable 1-enable,
Enable: 0-disable 1-enable,
When temperature calibration is enabled, if the value is positive, it will be added to the ambient temperature; if the value is negative, it will be subtracted from the ambient temperature.(unit:Celsius) |
`
{
"temperature_calibration": {
"enable": 1,
"temperature": 1.5
}
}
`
| setHumidityCalibration() | Enable or disable the ambient humidity calibration function.
0-disable 1-enable,
When humidity calibration is enabled, if the value is positive, it will be added to the ambient humidity; if the value is negative, it will be subtracted from the humidity temperature.(unit:%RH) |
`
{
"humidity_calibration": {
"enable": 1,
"humidity": 50
}
}
`
| setTemperatureLevelUpCondition() | The device will start braking (heating/cooling) at a lower level. If the target temperature is not reached by the detection time, it will switch to the next level of braking (heating/cooling) mode.
Type:0-heat 1-cool,
Time: detection time,unit: minute,
Temperature_control_tolerance:Temperature variation value, unit: celsius
|
`
{
"temperature_level_up_condition": {
"type": 0,
"time": 10,
"temperature_control_tolerance": 1
}
}
`
| setTemperatureSourceConfig() | Whether to enable external temperature. If external temperature is enabled, you need to set the external temperature timeout.
Source:0-disable 1-send downlink to modify 2-recieve the temperature sent by EM300-TH sensor,
Timeout:The timeout period for automatically disabling the external ambient temperature mode when no external ambient temperature data has been received for a certain period of time, unit:minute
|
`
{
"temperature_source_config": {
"source": 1,
"timeout": 10
}
}
`
| setOutsideTemperature() | When the WT201 has enabled the external temperature mode and the temperature source is from a downlink command, you can use this function to set the external ambient temperature via a downlink command. |
`
{ "temperature": 22.5 }
`
| setFreezeProtection() | When current temperature is lower than the protection E Freeze Protection temperature, switch control mode to EM Heat to adjust to protection temperature, then change back to the original control mode. Enable:0-disable 1-enable,
Temperature: protection Temperature,unit:celsius.
|
`
{
"freeze_protection_config": {
"enable": 1,
"temperature": 5
}
}
`
| setHumidityRange() | Set minimum and maximum humidity range. Both the minimum and maximum values must be between 0 and 100, unit:%RH |
`
{ "humidity_range": { "min": 30, "max": 60 } }
`
| setTemperatureDehumidify() | Set the value of Temp.Control and Dehumidify.
Enable:0-disable 1-enable,
temperature_tolerance:the value of Temp.Controland Dehumidify,unit:celsius. |
`
{ "temperature_dehumidify": { "enable": 1, "temperature_tolerance": 1 } }
`
| setFanDehumidify() | When the WT201 is in standby mode, if the ambient humidity exceeds the target humidity range, the WT201 will periodically turn on the fan for dehumidification.
Enable:0-disable 1-enable,
Execute_time: how long the fan runs within one hour, unit:minute.
|
`
{ "fan_dehumidify": { "enable": 1, "execute_time": 30 } }
`
| setCardConfig() | Configure card presence actions
Enable:0-disable,1-enable
action_type:0-power,1-plan

in_plan_type: when action_type is 1,Set the local schedule mode used by WT201 when the card is inserted; the default is Home mode. 0-wake, 1-away, 2- home, 3-sleep, 4- occupied, 5- vacant, 6- eco

out_plan_type: when action_type is 1,Set the local schedule mode used by WT201 when the card is removed; the default is away mode. 0-wake, 1-away, 2- home, 3-sleep, 4- occupied, 5- vacant, 6- eco

Invert:
0: Low level indicates card inserted (default)
1: High level indicates card inserted
|
`
{ "card_config": { "enable": 1, "action_type": 1, "in_plan_type": 0, "out_plan_type": 1, "invert": 0 } }
`
| setOBMode() | Configure the status of the reversing valve (O/B) of the WT201. |
`
{ "ob_mode": 1 }
`
| setWires() | Wiring settings,used to set the relays that are allowed to be used by the WT201 and O/B mode together |
`
{ "ob_mode": 1, "wires": { "y1": 1 } }
`
| setMulticastGroupConfig() | WT201 supports 4 broadcast groups. You can use this function to determine which broadcast groups the WT201 should enable. |
`
{ "multicast_group_config": { "dev_addr": "26011111", "nwk_s_key": "00112233445566778899AABBCCDDEEFF", "app_s_key": "FFEEDDCCBBAA99887766554433221100" } }
`
| setD2DEnable() | Enable D2D master/slave mode |
`
{ "d2d_master_enable": 1, "d2d_slave_enable": 0 }
`
| setD2DMasterId() | When the WT201 has enabled the external temperature mode and the source of the external temperature is from the EM300-TH via D2D, you can use this function to specify the deveui of the EM300-TH from which the WT201 receives data. The WT201 can receive temperature data from up to 5 EM300-TH devices via D2D and will calculate the average value. Id:range from 1 to 5
Dev_eui: the DevEUI of EM300-TH
|
`
{ "d2d_master_ids": ["AABBCCDDEEFF0011"] }
`
| setD2DMasterConfig() | Set D2D master configuration. |
`
{ "d2d_master_config": [{ "id": "AABBCCDDEEFF0011", "mode": 0 }] }
`
| setD2DSlaveConfig() | Set D2D slave configuration.|
`
{ "d2d_slave_config": [{ "id": "1122334455667788", "mode": 1 }] }
`
| setTemperatureAlarmConfig() | Configure temperature alarm thresholds.
alarm_type: 0-temperature threshold, 1-persistent low temperature threshold, 2-persistent high temperature threshold.

Condition:0-disable, 1-below, 2-above, 3-between, 4-outside

Min:
- Minimum value, unit: Celsius, int16/10
- When in continuous low temperature alarm mode, the difference value is stored here.

Max:
- Maximum value, unit: Celsius, int16/10
- When in continuous high temperature alarm mode, the difference value is stored here.

continue_time:duration,unit:s.
|
`
{ "temperature_alarm_config": { "alarm_type": 0, "condition": 0, "min": 10, "max": 35, "lock_time": 10, "continue_time": 60 } }
`
| setControlPermissions() | Restrict control permissions. 0-thermostat,1-Remote control|
`
{ "control_permissions": { "temperature": 1, "mode": 0 } }
`
| setOfflineControlMode() | Set how WT201 should respond when the external temperature times out.
0: keep current state
1: returen to thermostate control
2:disconnect all relays
|
`
{ "offline_control_mode": 1 }
`
| setWiresRelayChangeReport() | After you enable this feature, whenever the current relay status of the WT201 changes, the WT201 will report the updated relay wiring status. |
`
{ "wires_relay_change_report_enable": 1 }
`
| setAuxControlConfig() | This feature determines whether Y1 and Y2 or W1 and W2 should be activated simultaneously to enhance the temperature control effect when entering the second-stage temperature control |
`
{ "aux_control_config": { "y2_enable": 1, "w2_enable": 1 } }
`
| setScreenDisplayMode() | Configure screen display.
0: show all
1:show all without schedule plan
2: disable all
|
`
{ "screen_display_mode": 1 }
`
| setSystemProtectConfig() | Configure system protect (delay restart). Only when the minimum running duration passes, the heating or cooling system can start or stop working. Enable:0-disable 1-enable
Duration:range from 1 to 60, unit: minute
|
`
{ "system_protect_config": { "enable": 1, "duration": 10 } }
`
| setTargetTemperatureRange() | Set min/max target temp per mode. Set the adjustable range of the target temperature for WT201 in different temperature control modes.
temperature_control_mode: 0-heat,1-em heat, 2-cool, 3-auto.

min: Minimum target temperature,unit:celsius

max: Miaxmum target temperature,unit:celsius
|
`
{ "target_temperature_range": { "temperature_control_mode": 2, "min": 20, "max": 28 } }
`
| setFanControlDuringHeating() | Configure fan control when heating. Used to set whether the fan needs to be turned on when using a furnace/boiler for heating. If "Thermostat" is selected, the fan will be turned on during heating; otherwise, it will remain off. 0-furnace, 1- thermostat|
`
{ "fan_control_during_heating": 1 }
`
| setUnlockConfig() | Unlock device config. Combination key unlock configuration: set which buttons need to be pressed simultaneously to temporarily unlock the child lock. |
`
{ "unlock_config": 1 }
`
| setTemperatureLevelUpDownDelta() | Configure delta for up/down temperature transitions. If the difference between the target temperature and the ambient temperature exceeds delta1, it should switch to level 2; if it exceeds delta2, it should switch to level 3.
delta_1: temperature for delta1.unit: celsius

delta_2:temperature for delta1.unit: celsius
|
`
{ "temperature_level_up_down_delta": { "delta_1": 1, "delta_2": 2 } }
`
| setTargetTemperatureResolution() | Set resolution (0.5°C or 1°C). Set the resolution of the target temperature displayed on the WT201 screen. target_temperature_resolution:0- 0.5 resolution,1- 1 resolution. |
`
{ "target_temperature_resolution": 0.5 }
`
| setTemperatureUpDownEnable() | Enable/disable forward/backward temp change. Set whether the temperature control level of WT201 can be upgraded or downgraded. |
`
{ "temperature_up_down_enable": { "forward_enable": 1, "backward_enable": 1 } }
`
| setTemperatureControlForbiddenConfig() | Prevent specific temp modes. Disable certain temperature control modes in WT201. |
`
{ "temperature_control_forbidden_config": { "mode": [0, 2] } }
``