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

$ 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

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Test

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

REST API

Get lorawan thermostat list

GET /thermostat/milesight

maxResult(optional) range from 1-250 (default is 25) nextToken(optional) token for the succeeding page/request

Setting thermostat mode

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

Setting thermostat hold

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

Setting thermostat schedule

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
}

Retrieving historical data

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

Reboot the thermostat

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

Setting timezone

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)

Setting lock configuration

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

Setting report interval

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)

Setting fan-execute-time

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

Set compressor and aux combine enable (heat-pump)

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

Set wires relay configuration

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

Set Daylight Saving Time (DST) configuration

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] } }