tekmar Home Automation Protocol
Description
The tekmar home automation (tHA) protocol is a defined set of commands that may be used for communicating between a home automation device and a tHA gateway, this provides access to supported devices on a tekmarNet network connected to the tHA gateway.
tekmarNet
tekmar's tekmarNet network is similar in nature to CAN Bus, it is a broadcast serial bus where each node is able to send and receive messages, but not simultaneously. The tekmarNet network is limited to 400 baud and because of this limitation the tHA gateway gathers information from each of the supported devices on the network so that is it readily available when requested. Requests to update device data are also buffered (queued) by the tHA gateway; however, a response acknowledging an update is not sent until a response has been received from the tekmarNet device. This response may take a "long" time to receive in a busy network, if the device has not responded in two minutes the update should be considered timed out; however, it is still possible that the gateway will send a response.
Compatible Equipment
tekmarNet consists of two separate solutions. tekmarNet4 is a four wire system that allows communication between thermostats and boiler heating controls. tekmarNet2 is a two wire system that allow communication between thermostats and a zoning device called a zone manager. All tekmarNet2 thermostats require a compatible tekmarNet2 zone manager in order to operate. Newer tekmarNet thermostats support both tekmarNet2 and tekmarNet4 wiring topologies.
The device type accessible through the DeviceType method is listed in brackets.
- tekmarNet4 Gateway 482 - Serial Interface
- tekmarNet4 Thermostat 537 (100102) - 1 Stage Heat
- tekmarNet4 Thermostat 538 (100103) - 1 Stage Heat
- tekmarNet4 Thermostat 540 (100101) - 1 Stage Heat, 1 Stage Cool, 1 Fan
- tekmarNet4 Thermostat 541 (99301) - 1 Stage Heat
- tekmarNet4 Thermostat 542 (99302) - 1 Stage Heat
- tekmarNet4 Thermostat 543 (99401) - 2 Stage Heat
- tekmarNet4 Thermsotat 544 (99203) - 1 Stage Heat, 1 Stage Cool, 1 Fan
- tekmarNet4 Thermsotat 545 (99202) - 2 Stage Heat, 1 Stage Cool, 1 Fan
- tekmarNet4 Thermostat 546 (99201) - 2 Stage Heat, 2 Stage Cool, 2 Fan
- tekmarNet2 Thermostat 527 (102301) - 1 Stage Heat
- tekmarNet2 Thermostat 528 (102302) - 1 Stage Heat
-
tekmarNet2 Thermostat 529 (102303) - 2 Stage Heat
- tekmarNet2 Thermostat 530 (102304) - 1 Stage Heat, 1 Stage Cool, 1 Fan
- tekmarNet Thermostat 552 (105101) - 1 Stage Heat
- tekmarNet Thermostat 557 (104401) - 2 Stage Heat, 2 Stage Cool, 1 Fan
Protocol Stack
The tHA protocol has three layers, stating at the physical layer, the tHA 482 gateway uses RS-232 for communicating with the home automation network. The middle layer is the tekmar packet protocol (tpck) which is used for carrying various packet types, tHA being one, and message validation (checksum). The top layer of the stack is the tekmar-RPC (tRPC) layer, which is used to implement the actual tHA commands.
- tRPC / tHA - The tHA command set is implemented as tRPC messages.
- tpck - The tpck protocol is used for message validation.
- Physical layer (RS-232, USB, TCP/IP, etc)
Physical Layer
A serial (RS-232) interface is used on the tHA (482) gateway with the following parameters.
- No hardware flow control
- Full-duplex
- Baud Rate - 9600bps
- Data Bits - 8
- Parity - None
- Stop Bits - 1
The tHA (482) gateway uses a RJ45 connector described below.
RJ45 Male Connector Pin Numbering
|
Pin No. |
Name |
Notes/Description |
|
1 |
DSR/RI |
Data set Ready/ring indicator |
|
2 |
DCD |
Data Carrier Detect |
|
3 * |
DTR |
Data Terminal Ready |
|
4 * |
SGND |
Signal Ground |
|
5 * |
RD |
Receive Data |
|
6 * |
TD |
Transmit Data |
|
7 |
CTS |
Clear to Send |
|
8 |
RTS |
Request to Send |
* These pins are used.
The DTR pin is used for in circuit serial programming (ISP) to allow for future firmware upgrades.
tekmar Packet Protocol
Description
The tekmar packet (tpck) is a packet-based protocol that provides message validation. The protocol was designed to allow multiple protocols to be carried over the same serial link and therefore requires delimiters, packet identification, and validation.
Protocol Summary
Data is transferred byte-wise in binary packets which are delimited by Start-of-Frame (SOF) and End-of-Frame (EOF) characters. Byte stuffing with an Escape character is used to allow SOF, EOF, and Escape characters to be transmitted as data.
The packets are allowed to be segmented, but the segments are required to be sent and received in order. This allows packets to be carried over links that force the use of smaller data packages.
Packet Format
A packet is at least 5 bytes long and is made up as follows:
|
Byte Index |
Name |
Description |
|
0 |
SOF |
Start-of-Frame character. The value of this byte is always 0xCA. Any time a non-escaped SOF character is received, it is to be treated as the start of a new packet and if a packet was currently being received, it is dropped in favour of the new one. |
|
1 |
Length |
The Length field is an unsigned 8-bit value indicating the number of Data bytes being transferred in the packet, i.e. the SOF, Length, Type, Checksum, and EOF fields are not included in this count. |
|
2 |
Type |
The Type field is an unsigned 8-bit value indicating the type (format) of the data carried within the packet. See the table below for a description of the supported data types. |
|
3 - 3+N-1 |
Data |
These bytes constitute the data that the packet carries. The format of this data is dependent upon the Type field and is beyond the scope of this document. The number of bytes in this field is specified by the Length field (N). |
|
3+N |
Checksum |
The Checksum field is an unsigned 8-bit value that is calculated as the sum of the Length field, the Type field, and all the data bytes. During the summation of the fields, any 8-bit math overflows are ignored, i.e. the result is the sum modulo 256. |
|
4+N |
EOF |
This is the EOF character. The value of this byte is always 0x35. |
Byte Stuffing
If any byte in the Length, Type, Data, or Checksum fields have the value 0xCA, 0x35, or 0x2F, they must be preceded by an Escape character (0x2F). This Escape character, when detected by a receiving device will cause the byte to be ignored and the subsequent byte to be accepted as part of the packet.
The Escape character is a stuffed byte and does NOT contribute to the value of the Length field or Checksum fields.
Packet Types
The Type field specifies the data format being carried, only the tRPC type is used by the tHA protocol. For the tHA protocol the tRPC type must be used, all packets with types that are not tPRC are ignored by the tHA gateway.
|
Type |
Name |
Description |
|
0 |
General |
The data format of these packets is undefined and packets of this type can be used to carry almost anything as long as the involved devices agree on the format. |
|
6 |
tRPC |
Packets of this type carry trpc data. |
tekmar-RPC
Description
The tRPC protocol is a method of sending and receiving serialized objects.
tRPC is a binary protocol that has three main components:
- Service
- The service types identifies the action/direction of the message. There are five service types described below.
- Method
- Specifies the type of data contained in the message.
- Data
- The data, which can be multiple parameters packed together (the size is method/service specific).
Specification
tRPC Protocol Diagram
|
Byte Index |
0 |
1 - 4 |
5 - 5+N-1 |
|
Content |
Service |
Method |
Data |
Data (N) must be less than or equal to 128 bytes.
Byte Packing
All data that consists of more than one byte is byte packed. For example a 32-bit number such as the method is packed in the following way.
1 PackedMethod[0] = (uint8_t)((method ) & 0xFF);
2 PackedMethod[1] = (uint8_t)((method >> 8) & 0xFF);
3 PackedMethod[2] = (uint8_t)((method >> 16) & 0xFF);
4 PackedMethod[3] = (uint8_t)((method >> 24) & 0xFF);
Service
|
Service |
Value |
Description |
|
Update |
0x00 |
This is used to update or change the specified value (by method) on the receiving device. |
|
Request |
0x01 |
This is used to request (read) a value from a device. |
|
Report |
0x02 |
This is to indicate that the message is a broadcast with no specific recipient. |
|
Response:Update |
0x03 |
This is used when a device is responding to an update. The value returned is the value that was accepted by the receiving device which may differ from the desired value. |
|
Response:Request |
0x04 |
This is used when a device is responding to a request. |
Method
The Method specifies the type of data that is contained in the message.
Data
The data is an object with properties specified by the method and possibly the service. The maximum size of the parameter data is 128 bytes.
tHA Command Set
There are five services used in conjunction with the methods:
-
Update - Indicates that the data associated with the method is to be updated.
-
Request - Indicates that the data associated with the method is desired.
-
Report - Indicates that the data in the message is that associated with the method.
-
Response:Update - Is sent in response to an update and contains the accepted value(s).
-
Response:Request - Is sent in response to an request and contains the requested data.
A table of available commands is listed below, for more detail on specific methods please refer to the tHA Method Descriptions.
|
Method Name |
Method ID |
Data Size (Bytes) |
Data Parameters |
| NullMethod |
0x000 |
0 |
None |
| NetworkError |
0x107 |
2 |
error |
| ReportingEnable |
0x10F |
1 |
enable |
| OutdoorTemperature |
0x117 |
2 |
temperature |
| DeviceAttributes |
0x11F |
4 |
address, attributes |
| ModeSetting |
0x127 |
3 |
address, mode |
| ActiveDemand |
0x12F |
3 |
address, demand |
| CurrentTemperature |
0x137 |
4 |
address, temperature |
| HeatSetpoint |
0x13F |
4 |
address, setback_state, setpoint |
| CoolSetpoint |
0x147 |
4 |
address, setback_state, setpoint |
| SlabSetpoint |
0x14F |
4 |
address, setback_state, setpoint |
| FanPercent |
0x157 |
4 |
address, setback_state, percent |
| TakingAddress |
0x15F |
4 |
old_address, new_address |
| DeviceInventory |
0x167 |
2 |
address |
| SetbackEnable |
0x16F |
1 |
enable |
| SetbackState |
0x177 |
3 |
address, setback_state |
| SetbackEvents |
0x17F |
3 |
address, events |
| FirmwareRevision |
0x187 |
2 |
revision |
| ProtocolVersion |
0x18F |
2 |
version |
| DeviceType |
0x197 |
6 |
address, type |
| DeviceVersion |
0x19F |
6 |
address, version |
| DateTime |
0x1A7 |
7 |
year, month, day, weekday, hour, minute |
tHA Protocol Diagram
The tHA protocol diagram is the tpck and tRPC protocols combined.
|
Byte Index |
0 |
1 |
2 |
3 |
4 - 7 |
8 - 8+N-1 |
8+N |
9+N |
|
Content |
SOF |
Length |
Type |
Service |
Method |
Data |
Checksum |
EOF |
tHA Service Descriptions
The following services are sent to the tHA gateway:
Update
When an Update is sent to the tHA gateway the data associated with the specific command is updated with the supplied values. A Response:Request is then sent from the tHA gateway containing the accepted values, which may differ from the values sent. If a Response:Update is not received two minutes after this message was sent the update should be considered timed out; however, it is still possible that the gateway will send a response.
Request
When a Request is sent to the tHA gateway the data associated with the specified command is returned in Response:Request message.
The following services are sent from the tHA gateway:
Response:Update
This message is sent from the tHA gateway in response to an Update command, the accepted values for the updated parameters are contained in this message. If a Response:Update is not received two minutes after this message was sent the update should be considered timed out; however, it is still possible that the gateway will send a response.
Response:Request
This message is sent from the tHA gateway in response to a Request command, the data associated with the requested command is contained in this message.
Report
This message contains the same information as a Response:Request but is unsolicited, these messages may be turned on or off with the ReportingEnable command.
tHA Method Descriptions
NullMethod
Description
A Null message. This message will be sent if an unsupported method is received by the gateway device.
Method ID
0x000
Data
None
NetworkError
Description
Current network (tekmarNet) error, this will be non-zero if there is an error present on the network.
Services
Update
Updating the network error a valid operation, the gateway will respond by sending a Response:Update containing the current network error.
Request
When a request is received the gateway device responds by sending Response:Request containing the current network error.
Report
Contains the current network error.
Method ID
0x107
Data
(uint16_t) The current network error, non-zero value indicates an error is present.
Example
To request the network error:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x01 | 0x07 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x16 | 0x35 |
Copy and paste to Termite: 0xca 0x07 0x06 0x01 0x07 0x01 0x00 0x00 0x00 0x00 0x16 0x35
If there are no network errors, the following response:request is provided:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x04 | 0x07 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x19 | 0x35 |
ReportingEnable
Description
The reporting enable state indicates whether the control reports information or if it must be requested. Reports of the commands listed below are sent every one minute or on change whenever reporting is enabled.
-
TakingAddress - This is report is sent even when reporting is disabled.
-
NetworkError - Only reported if a network error is present.
-
CurrentTemperature - Always reported when enabled.
-
ActiveDemand - Only reported if the device has at one of the HeatSetpoint and CoolSetpoint attributes.
-
SetbackState - Only reported if setback is enabled.
-
HeatSetpoint - Only reported if the most current or most recent active demand was heating and the device has the HeatSetpoint Attribute.
-
CoolSetpoint - Only reported if the most current or most recent active demand was cooling and the device has the CoolSetpoint attribute.
-
SlabSetpoint - Only reported if the device has the SlabSetpoint attribute.
-
DeviceAttributes - Only reported if the device has the SlabSetpoint attribute.
-
FanPercent - Only reported if the device has the FanPercent attribute.
Services
Update
When an update is received the gateway device sets the reporting state to the value of the enable parameter, (off - 0, on - 1).
A Response:Update will be sent containing the accepted reporting enable value.
Request
When a request is received the gateway device sends a Response:Request, which contains the reporting enable parameter.
Report
A report contains the current reporting enable value.
Method ID
0x10F
Data
(uint8_t) enable
- 1 - reporting is enabled.
- 0 - reporting is disabled.
Example
To enable reporting:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | CS | EOF |
| Hex Value | 0xca | 0x06 | 0x06 | 0x00 | 0x0f | 0x01 | 0x00 | 0x00 | 0x01 | 0x1d | 0x35 |
Copy and paste to Termite: 0xca 0x06 0x06 0x00 0x0f 0x01 0x00 0x00 0x01 0x1d 0x35
To disable reporting:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | CS | EOF |
| Hex Value | 0xca | 0x06 | 0x06 | 0x00 | 0x0f | 0x01 | 0x00 | 0x00 | 0x00 | 0x1c | 0x35 |
Copy and paste to Termite: 0xca 0x06 0x06 0x00 0x0f 0x01 0x00 0x00 0x00 0x1c 0x35
OutdoorTemperature
Description
The outdoor temperature that is currently in use on the network.
Services
Update
When the gateway receives an update the local outdoor temperature is set to the value provided, this must be updated every 4 minutes to remain valid. A Response:Update is then sent containing the network temperature, which will not be the same as the local temperature if another device on the network is providing outdoor temperatures
If there are no other devices providing a valid outdoor temperature on the network and the outdoor temperature on the gateway remains valid it become the device providing the network with the outdoor temperature.
Request
When a request is sent to the gateway it will respond with a Response:Request containing the current outdoor temperature used by the network.
Report
A report contains the current outdoor temperature used by the network.
Method ID
0x117
Data
(uint16_t) The outdoor temperature in degH.
Example
Request outdoor temperature:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x01 | 0x17 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x26 | 0x35 |
Copy and paste to Termite: 0xca 0x07 0x06 0x01 0x17 0x01 0x00 0x00 0x00 0x00 0x26 0x35
If there is no outdoor sensor connected, the data bits reported are FF FF:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x04 | 0x17 | 0x01 | 0x00 | 0x00 | 0xff | 0xff | 0x27 | 0x35 |
To update the outdoor temperature to 80 degree Fahrenheit:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x00 | 0x17 | 0x01 | 0x00 | 0x00 | 0x72 | 0x06 | 0x9d | 0x35 |
Copy and paste to Termite: 0xca 0x07 0x06 0x00 0x17 0x01 0x00 0x00 0x72 0x06 0x9d 0x35
DeviceAttributes
Description
The DeviceAttributes method provides access to an attribute mask that indicates the attributes of that device. The possible attributes that a device may have are: heating, cooling, slab setpoint, and fan operation.
Services
Update
Updating the attributes of a device is not a valid operation, the device attributes of the specified device will be returned in a Response:Update message and the attribute data sent is ignored.
Request
When a request is sent the attributes of the specified device will be returned in a Response:Update message.
Report
A report contains the device attributes of the device specified by the address.
Method ID
0x11F
Data
(uint16_t) Address of the device.
(uint16_t) Attribute mask, see below for attribute mask values.
Attribute Masks
- 0x01 - Zone/Room Heating
- 0x02 - Zone/Room Cooling
- 0x04 - Slab Setpoint
- 0x08 - Fan Percent
Example
To request the device attributes of a thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x01 | 0x1f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x00 | 0x31 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x01 0x1f 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x31 0x35
The response of a heat, cool and fan thermostat with address 0001 is:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x04 | 0x1f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x0b | 0x00 | 0x3f | 0x35 |
ModeSetting
Description
The ModeSetting method provides access to the operational mode of the device, which is one of the following: Off, Heat, Auto, Cool, of Vent. Vent is used in few devices and so it is recommended that it is not provided to the user as an option.
Services
Update
When an update is received by the gateway it sets the mode of the specified device. The valid modes are listed below; however, not all modes are supported on all devices. If an invalid mode is written to a device it will revert to a mode that is supported.
The supported modes can be inferred from the device attributes.
- Off - Always supported.
- Heat - Must have heating or slab setpoint attribute.
- Auto - Must have both heating and cooling attributes.
- Cool - Must have cooling attribute.
- Vent - Must have fan attribute.
Request
When a request is received by the gateway it responds by sending a Response:Request containing the mode setting for the specified device.
Report
A report contains the mode setting for the device specified by the address.
Method ID
0x127
Data
(uint16_t) Address of the device
(uint8_t) Mode
- 0x00 - Off
- 0x01 - Heat
- 0x02 - Auto
- 0x03 - Cool
- 0x04 - Vent
Example
To change thermostat with address 0001 to mode heat:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x27 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x01 | 0x00 | 0x39 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x27 0x01 0x00 0x00 0x01 0x00 0x01 0x00 0x39 0x35
To change thermostat with address 0001 to mode cool:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x27 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x03 | 0x00 | 0x3b | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x27 0x01 0x00 0x00 0x01 0x00 0x03 0x00 0x3b 0x35
To change thermostat with address 0001 to mode auto:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x27 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x02 | 0x00 | 0x3a | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x27 0x01 0x00 0x00 0x01 0x00 0x02 0x00 0x3a 0x35
To change thermostat with address 0001 to mode off:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x27 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x00 | 0x38 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x27 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x38 0x35
ActiveDemand
Description
The ActiveDemand method provides access to the current operating demand: heating, cooling, or none.
Services
Update
Updating the active demand is not a valid operation, the demand parameter sent will be ignored and the current active demand of the specified device will be sent in a Response:Update message.
Request
When a request is received by the gateway it responds by sending a Response:Request containing the current active demand of the specified device.
Report
A report contains the active demand of the device specified by the address.
Method ID
0x12F
Data
(uint16_t) Address of the device.
(uint8_t) Demand
- 0x00 - None
- 0x01 - Heat
- 0x03 - Cool
Example
To request the active demands on the thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Escape | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x08 | 0x06 | 0x01 | 0x2f | 0x2f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x40 | 0x35 |
Copy and paste to Termite: 0xca 0x08 0x06 0x01 0x2f 0x2f 0x01 0x00 0x00 0x01 0x00 0x00 0x40 0x35
If the thermostat with address 0001 is currently cooling, then the response is:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Escape | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x08 | 0x06 | 0x04 | 0x2f | 0x2f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x03 | 0x46 | 0x35 |
CurrentTemperature
Description
The CurrentTemperature method provides access to the temperature that is being actively controlled by the specified device.
Services
Update
Updating the temperature is not a valid operation, the current control temperature of the device will be sent in a Response:Update message.
Request
When a request is received by the gateway it responds by sending a Response:Request containing the current control temperature of the specified device.
Report
A report contains the current control temperature of the specified device.
Method ID
0x137
Data
(uint16_t) Address of the device.
(uint16_t) temperature being controlled in degH (see definitions).
Example
To request the current temperature of thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x01 | 0x37 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x00 | 0x49 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x01 0x37 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x49 0x35
The response could be:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x04 | 0x37 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x5f | 0x06 | 0xb1 | 0x35 |
HeatSetpoint
Description
The HeatSetpoint method provides access to the heating setpoint for the specified device and setback state.
A value of THA_CURRENT = 0x07 may be used to request the current setpoint instead of specifying the actual setback state.
Services
Update
When an update is sent to the gateway the heating setpoint of the specified device and setback state is set. The accepted value is sent in a Response:Update message.
If the device does not support this setting then THA_NA_8 (see definitions) is returned.
Request
When a request is received by the gateway it responds by sending a Response:Request which contains the specified heating setpoint of the device.
If the device does not support this setting then THA_NA_8 is returned.
Report
A report contains the specified heating setpoint of the device.
Method ID
0x13F
Data
(uint16_t) Address of the device.
(uint8_t) Setback state of the device (see definitions for possible values).
(uint8_t) Temperature being targeted in degE (see definitions).
Example
To update the heating sepoint on a thermostat with address 0001 to 70 degrees Fahrenheit:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x3f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x07 | 0x2a | 0x81 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x3f 0x01 0x00 0x00 0x01 0x00 0x07 0x2a 0x81 0x35
CoolSetpoint
Description
The CoolSetpoint method provides access to the heating setpoint for the specified device and setback state.
A value of THA_CURRENT = 0x07 may be used to request the current setpoint instead of specifying the actual setback state.
Services
Update
When an update is sent to the gateway the cooling setpoint of the specified device and setback state is set. The accepted value is sent in a Response:Update message.
If the device does not support this setting then THA_NA_8 is returned.
Request
When a request is received by the gateway it responds by sending a Response:Request which contains the specified cooling setpoint of the device.
If the device does not support this setting then THA_NA_8 is returned.
Report
A report contains the specified cooling setpoint of the device.
Method ID
0x147
Data
(uint16_t) Address of the device.
(uint8_t) Setback state of the device (see definitions for possible values).
(uint8_t) temperature being targeted in degE.
Example
To update the cooling sepoint on a thermostat with address 0001 to 70 degrees Fahrenheit:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x47 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x07 | 0x2a | 0x89 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x47 0x01 0x00 0x00 0x01 0x00 0x07 0x2a 0x89 0x35
SlabSetpoint
Description
The SlabSetpoint method provides access to the heating setpoint for the specified device and setback state. In order to support SlabSetpoint, the thermostat must be configured to have the air temperature sensing sensor disabled and the floor temperature sensor must be enabled.
A value of THA_CURRENT = 0x07 may be used to request the current setpoint instead of specifying the actual setback state.
Services
Update
When an update is sent to the gateway the slab setpoint of the specified device and setback state is set. The accepted value is sent in a Response:Update message.
If the device does not support this setting then THA_NA_8 is returned.
Request
When a request is received by the gateway it responds by sending a Response:Request which contains the specified slab setpoint of the device.
If the device does not support this setting then THA_NA_8 is returned.
Report
A report contains the specified slab setpoint of the device.
Method ID
0x14F
Data
(uint16_t) Address of the device.
(uint8_t) Setback state of the device (see definitions for possible values).
(uint8_t) temperature being targeted in degE.
Example
To update a thermostat with address 0001 with a slab (floor) setpoint of 70 degree Fahrenheit:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x4f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x07 | 0x2a | 0x91 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x4f 0x01 0x00 0x00 0x01 0x00 0x07 0x2a 0x91 0x35
FanPercent
Description
The FanPercent method provides access to the heating setpoint for the specified device and setback state.
The range of possible values is 0 to 100, 0 being Auto and 100 representing 100%.
Note for Thermostats 544, 545, 546:
The range of possible values is 0 to 10, 0 being Auto and 10 representing 100%.
A value of THA_CURRENT = 0x07 may be used to request the current fan percent instead of specifying the actual setback state.
Services
Update
When an update is sent to the gateway the fan percent of the specified device and setback state is set. The accepted value is sent in a Response:Update message.
If the device does not support this setting then THA_NA_8 is returned.
Request
When a request is received by the gateway it responds by sending a Response:Request which contains the specified fan percent of the device.
If the device does not support this setting then THA_NA_8 is returned.
Report
Contains the specified fan percent of the device.
Method ID
0x157
Data
(uint16_t) Address of the device.
(uint8_t) Setback state of the device (see definitions for possible values).
(uint8_t) Fan setting in 1% increments. 0 = Auto (off when not heating or cooling), 10 = 10%, 90 = 90%, 100 = On
Example
To update a thermostat with address 0001 to have a fan duty cycle of 50%:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x00 | 0x57 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x07 | 0x32 | 0xa1 | 0x35 |
Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x57 0x01 0x00 0x00 0x01 0x00 0x07 0x32 0xa1 0x35
The response:request will be:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x03 | 0x57 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x04 | 0x32 | 0xa1 | 0x35 |
TakingAddress
Description
The TakingAddress method used to indicate that the address of a device has changed. This message will be sent as a report contaning the old address and the new address.
Services
Update
The Update service is not a valid operation for the TakingAddress method and will be ignored, no response will be sent.
Request
The Request service is not a valid operation for the TakingAddress method and will be ignored, no response will be sent.
Report
A report contains the old (current) address of a device and the new address that it is taking on. This report is sent even if reporting is disabled.
Method ID
0x15F
Data
(uint16_t) Old (current) address of the device.
(uint16_t) New address of the device.
Example
If a thermostat's address is manually changed from 0001 to 0002, the report will be:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(2) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x09 | 0x06 | 0x02 | 0x5f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x02 | 0x00 | 0x74 | 0x35 |
DeviceInventory
Description
The DeviceInventory method provides access to the devices inventory. It is possible to list all devices in the inventory, check to see if a specific device exists, delete a device from the inventory, and delete all devices in the inventory. If a device is deleted it will automatically be re-added once a the gateway receives another message from it on the tekmarNet side.
Services
Update
Sending an update to the gateway can have to possible effects depending on the value of the address parameter.
Address = 0
-
The entire device inventory is deleted and subsequently rebuilt. A Response:Update with the address = 0 will be returned to indicate that the operation was successful.
Address != 0
-
The device specified by the address is removed. If the device was successfully removed a Response:Update is sent containing the address of the device that was deleted. If the device with the address supplied does not exist, no action is taken and a Response:Update is sent with the address = THA_NA_16.
Request
Sending an request to the gateway can have to possible effects depending on the value of the address parameter.
Address = 0
-
The entire device inventory will be listed. A Response:Request with the address of each device will be sent and a final Response:Request with an address = 0 will be sent to indicate that all devices have been listed.
Address != 0
-
A Response:Request will be sent containing the address specified if the device is present or with THA_NA_16 if it is not.
Report
This is not used.
Method ID
0x167
Data
(uint16_t) Address of the device.
Example
To request the device inventory:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x01 | 0x67 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x76 | 0x35 |
Copy and paste to Termite: 0xca 0x07 0x06 0x01 0x67 0x01 0x00 0x00 0x00 0x00 0x76 0x35
If there is only one thermostat with address 0001 connected, the reponse:request will be:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x04 | 0x67 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x7a | 0x35 |
together with:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x04 | 0x67 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x79 | 0x35 |
The first message is a report that a thermostat with device 0001 is detected. The second message has an address of 0000 to signify the end of the device inventory list.
SetbackEnable
Description
The SetbackEnable method allows for turning setback support on or off. If setback support is off the gateway sets all setback state setpoints to the same value, effectively disabling setback. If setback support is enabled then the gateway allows for three unique setpoints: Occ, UnOcc, and Away. Some devices support four event schedules: Wake, Occ, UnOcc, and Sleep in these cases the gateway sets Wake = Occ and UnOcc = Sleep. This is done so that device specific operation can be ignored and all devices can be handled in the same manner.
Services
Update
When an Update is sent to the gateway the setback enable parameter is set to the specified value and a Response:Update is sent containing the accepted value.
Request
When an Request is sent to the gateway a Response:Request is sent containing the setback enable parameter.
Report
This is not used.
Method ID
0x16F
Data
(uint8_t) enable
- 0x00 - Disabled means that one setpoint is available, wake = unocc = occ = sleep = away.
- 0x01 - Enabled means that three unique setpoints are available with four events (wake, unocc, occ, sleep), where wake = occ and unocc = sleep and away.
Example
To update to enable setback schedules:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | CS | EOF |
| Hex Value | 0xca | 0x06 | 0x06 | 0x00 | 0x6f | 0x01 | 0x00 | 0x00 | 0x01 | 0x7d | 0x35 |
Copy and paste to Termite: 0xca 0x06 0x06 0x00 0x6f 0x01 0x00 0x00 0x01 0x7d 0x35
To update to disable setback schedules:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | CS | EOF |
| Hex Value | 0xca | 0x06 | 0x06 | 0x00 | 0x6f | 0x01 | 0x00 | 0x00 | 0x00 | 0x7c | 0x35 |
Copy and paste to Termite: 0xca 0x06 0x06 0x00 0x6f 0x01 0x00 0x00 0x00 0x7c 0x35
SetbackState
Description
The SetbackState method provides access to the setback state (Wake, UnOcc, Occ, Sleep) of the specified device.
Services
Update
Updating the setback state is not a supported operation, the gateway will respond by sending a Response:Update containing the current setback state of the specified device.
Request
When a Request is received by the gateway it will respond by sending a Response:Request containing the current setback state of the specified device.
Report
A Report containing the current setback state of the specified device.
Method ID
0x177
Data
(uint16_t) Address of the device.
(uint8_t) Setback state
- 0x00 - WAKE ( Wake state, 4 event schedule)
- 0x01 - UNOCC_4 (Unoccupied state, 4 event schedule)
- 0x02 - OCC_4 (Occupied state, 4 event schedule)
- 0x03 - SLEEP (Sleep state, 4 event schedule)
- 0x04 - OCC_2 (Occupied state, 2 event schedule)
- 0x05 - UNOCC_2 (Unoccupied state, 2 event schedule)
- 0x06 - AWAY
Example
To request the current setback state on a thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x08 | 0x06 | 0x01 | 0x77 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x88 | 0x35 |
Copy and paste to Termite: 0xca 0x08 0x06 0x01 0x77 0x01 0x00 0x00 0x01 0x00 0x00 0x88 0x35
A response:request from thermostat with address 0001 that is in the occupied time period would be:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x08 | 0x06 | 0x04 | 0x77 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x04 | 0x8f | 0x35 |
SetbackEvents
Description
The SetbackEvents method provides access to the number of setback events for the specified device. This is either zero (no schedule), two events, or four events.
Services
Update
Updating the setback events parameter is not a supported operation, the gateway will respond by sending a Response:Update containing the current value of the setback events parameter.
Request
When a Request is received by the gateway it responds by sending a Response:Request containing the setback events configuration of the specified device.
Report
A Report contains the setback events configuration of the specified device.
Method ID
0x17F
Data
(uint16_t) Address of the device.
(uint8_t) Setback events
- 0x00 - Zero events, no schedule is running.
-
0x01 - Two events (Occ, UnOcc). This is a commercially-oriented schedule intended for buildings that are cycle between occupied and unoccupied only once per day.
-
0x02 - Four events (Wake, UnOcc, Occ, Sleep). This is a typical residential schedule configuration that allows for a range of household occupancy cycling patterns.
Example
To request the number of setback events supported by a thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | CS | EOF |
| Hex Value | 0xca | 0x08 | 0x06 | 0x01 | 0x7f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x90 | 0x35 |
Copy and paste to Termite: 0xca 0x08 0x06 0x01 0x7f 0x01 0x00 0x00 0x01 0x00 0x00 0x90 0x35
FirmwareRevision
Description
The FirmwareRevision method provides access to the firmware revision of the gateway device.
Services
Update
Updating the firmware revision is not supported, no response will be given to this command.
Request
When a Request is received by the gateway it responds by sending a Response:Request containing the firmware revision.
Report
Not used.
Method ID
0x187
Data
(uint16_t) the firmware revision running on the gateway device.
Example
Pressing the 482 Test button will result in two messages, the first of which is the 482 firmware version.
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x02 | 0x87 | 0x01 | 0x00 | 0x00 | 0x74 | 0x00 | 0x0b | 0x35 |
Data(0) indicates that the 482 is using protocol version hexadecimal 74, which is 116 in decimal.
ProtocolVersion
Description
The ProtocolVersion method provides access to the tHA protocol version of the gateway device.
Services
Update
Updating the protocol version is not supported, no response will be given to this command.
Request
When a Request is received by the gateway it responds by sending a Response:Request containing the protocol version.
Report
Not used.
Method ID
0x18F
Data
(uint16_t) the protocol version running on the gateway device.
Example
Pressing the 482 Test button will result in two messages, the second of which is the protocol version.
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | CS | EOF |
| Hex Value | 0xca | 0x07 | 0x06 | 0x02 | 0x8f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0xa0 | 0x35 |
Data(0) indicates that the 482 is using protocol version 01.
DeviceType
Description
The DeviceType method provides access to the device type at the specified address.
Services
Update
Updating the device type is not supported, no response will be given to this command.
Request
When a Request is received by the gateway it responds by sending a Response:Request containing the device type of the specified device.
Report
Not used.
Method ID
0x197
Data
(uint16_t) address of the device
(uint32_t) the device type.
Example
To request the device type of the thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | Data(5) | Data(6) | CS | EOF |
| Hex Value | 0xca | 0x0b | 0x06 | 0x01 | 0x97 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0xab | 0x35 |
Copy and paste to Termite: 0xca 0x0b 0x06 0x01 0x97 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0xab 0x35
The response:request for a thermostat model 545 (99202) is:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | Data(5) | Data(6) | CS | EOF |
| Hex Value | 0xca | 0x0b | 0x06 | 0x04 | 0x97 | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x82 | 0x83 | 0x01 | 0x00 | 0xb4 | 0x35 |
The type number in hexadecimal is 18382. When changed to decimal this is 99202.
DeviceVersion
Description
The DeviceVersion method provides access to the firmware version running on the specified device.
Services
Update
Updating the device version is not supported, no response will be given to this command.
Request
When a Request is received by the gateway it responds by sending a Response:Request containing the software version of the specified device.
Report
Not used.
Method ID
0x19F
Data
(uint16_t) address of the device.
(uint32_t) the software version running on the device. In decimal, the last two numbers correspond to the firmware version letter, starting with A=0 and Z=25.
Example
To request the firmware version of a thermostat with address 0001:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | Data(5) | Data(6) | CS | EOF |
| Hex Value | 0xca | 0x0b | 0x06 | 0x01 | 0x9f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0xb3 | 0x35 |
Copy and paste to Termite: 0xca 0x0b 0x06 0x01 0x9f 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0xb3 0x35
The response of a thermostat model 545 could be:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | Data(5) | Data(6) | CS | EOF |
| Hex Value | 0xca | 0x0b | 0x06 | 0x04 | 0x9f | 0x01 | 0x00 | 0x00 | 0x01 | 0x00 | 0xaa | 0xb8 | 0x01 | 0x00 | 0x19 | 0x35 |
The firmware version in hexadecimal is 1b8aa. In decimal this is 112810. Checking the firmware version on the thermostat will show J11 28K. The last two digits 10 are correspond to the letter K in the alphabet.
DateTime
Description
The DateTime method sets the date and time of the network.
Services
Update
When an Update is received by the gateway it sets the date and time of the network to the supplied values and a Response:Update is sent. If the date and time are valid they are returned unchanged, if they are not valid the Response:Update will contain THA_NA values.
Request
Not used.
Report
Not used.
Method ID
0x1A7
Data
(uint16_t) year - 2000 to 2255.
(uint8_t) month - 1 to 12 (January = 1, December = 12)
(uint8_t) day - 1 to 31
(uint8_t) weekday - 1 to 7 (Monday = 1, Sunday = 7)
(uint8_t) hour - 0 to 23
(uint8_t) minute - 0 to 59
Example
To update the time and date to Tuesday, July 26, 2012 at 10:27am:
| Byte Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 |
| Content | SOF | Length | Type | Service | Method(0) | Method(1) | Method(2) | Method(3) | Data(0) | Data(1) | Data(3) | Data(4) | Data(5) | Data(6) | Data(7) | CS | EOF |
| Hex Value | 0xca | 0x0c | 0x06 | 0x00 | 0xa7 | 0x01 | 0x00 | 0x00 | 0xdc | 0x07 | 0x06 | 0x1a | 0x02 | 0x0a | 0x1b | 0xe4 | 0x35 |
Copy and paste to Termite: 0xca 0x0c 0x06 0x00 0xa7 0x01 0x00 0x00 0xdc 0x07 0x06 0x1a 0x02 0x0a 0x1b 0xe4 0x35
Note that if the thermostat daylight savings time setting is set on, the time will advance by 1 hour if within the daylight savings time period.
Definitions
Addressing
Addresses are 16 bit unsigned integers with the following form:
PBNN
P = Port, The physical port that the device is attached to on the gateway. The 482 has five physical ports, zero through four.
482 tN4 Bus 0 (terminals 3 & 4) = 0
482 tN4 Bus 1 (terminals 5 & 6) = 1
482 tN4 Bus 2 (terminals 7 & 8) = 2
482 tN4 Bus 3 (terminals 9 & 10) = 3
482 tN4 Bus 4 (terminals 11 & 12) = 4
B = Bus, The water temperature bus that the device belongs to, this is defined by the connection to the system control. The boiler temperature bus number varies depending on the system control model that the thermostat is connected to.
274 tN4 Boiler Bus = 1
275 tN4 Boiler Bus = 1
400 tN4 Boiler Bus = 1
401 tN4 Boiler Bus = 1
402 tN4 Mix Bus = 1
402 tN4 Boiler Bus = 2
420 tN4 Boiler Bus = 1
421 tN4 Mix Bus = 1
422 tN4 Mix1 Bus = 1
422 tN4 Boiler or Mix2 Bus = 2
423 tN4 Bus1 = 1
423 tN4 Bus2 = 2
423 tN4 Bus3 = 3
423 tN4 Boiler Bus = 4
If a device is not connected to a system control it is said to be in a stand-alone network. These networks will report a bus of zero (B = 0) and will display NN on the device.
NN = Node, The node of the (thermostat) device on its bus. The address that is visible on a device will be B:NN when connected to system control. When not connected to system control (stand-alone network), the address is shown as NN. The device number is a two digit number that ranges from 01 to 24 and can be determined from the device address shown on the display of the device.
Example 1:
A thermostat with bus and node address of b:01 is wired a model 400 controller boiler bus and in turn is wired to the 482 on port 0. This address is 0101.
Example 2:
A thermostat with bus and node address of b:24 is wired a model 423 controller boiler bus and in turn is wired to the 482 on port 0. This address is 0424.
Example 3:
A group of thermostats are wired together to create a stand-alone network. A thermostat with node address 15 is wired to the 482 on port 0. This address is 0015.
Degrees H
Degrees H is a unit of temperature used internally with tekmar.
To Convert between units the following equation is used:
degH = 10*(degF) + 850
Degrees E
Degrees E is a unit of temperature used internally with tekmar.
To Convert between units the following equation is used:
degE = 2*(degC)
Setback States
WAKE, OCC_4, UNOCC_4, and SLEEP are used on devices that have a 4-event schedule.
OCC_2 and UNOCC_2 are used on devices that have a 2-event schedule.
AWAY is used on all devices.
- 0x00 - WAKE
- 0x01 - UNOCC_4
- 0x02 - OCC_4
- 0x03 - SLEEP
- 0x04 - OCC_2
- 0x05 - UNOCC_2
- 0x06 - AWAY
- 0x07 - THA_CURRENT
Not Applicable or Invalid Values
Values used to indicate an unknown or undefined quantity.
- THA_NA_8 = 0xFF
- THA_NA_16 = 0xFFFF
- THA_NA_32 = 0xFFFFFFFF
Examples
I this examples of sending requests/updates and receiving the responses will be given.
Example 1
Requesting the complete device inventory (all supported devices on the network). In this example there are two devices on the network with address = 0001 and address = 0002.
Service - Request (0x01)
Method - DeviceInventory (0x167)
Data - address = 0
or for the future written as:
Request DeviceInventory <address = 0000>
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x07 |
0x06 |
0x01 |
0x67 |
0x01 |
0x00 |
0x00 |
0x00 |
0x00 |
0x76 |
0x35 |
The checksum is calculated as the sum of the length field, the type field, and all the data bytes ignoring 8-bit overflows (modulo 256).
CS = 0x07 + 0x06 + 0x01 + 0x67 + 0x01 + 0x00 + 0x00 + 0x00 + 0x00 = 0x76
The response from the gateway will be as follows:
Response:Request DeviceInventory <address = 0001>
Response:Request DeviceInventory <address = 0002>
Response:Request DeviceInventory <address = 0000> - Indicates that listing the device inventory is complete.
The byte stream for the first response is as follows:
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x07 |
0x06 |
0x04 |
0x67 |
0x01 |
0x00 |
0x00 |
0x01 |
0x00 |
0x7A |
0x35 |
Example 2
Requesting the current heat setpoint from the device with address = 1401.
We will assume that device 1401 is in the OCC_4 state and has a setpoint of 74F or approx. 23.5C (47degE).
Request HeatSetpoint <address = 1401><setback_state = THA_CURRENT>
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Setback State |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x08 |
0x06 |
0x01 |
0x3F |
0x01 |
0x00 |
0x00 |
0x79 |
0x05 |
0x07 |
0xD4 |
0x35 |
A setpoint could also be sent in the request and it would still be valid, the gateway will simply ignore it; therefore, the following byte stream would also be valid:
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Setback State |
Setpoint |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x09 |
0x06 |
0x01 |
0x3F |
0x01 |
0x00 |
0x00 |
0x79 |
0x05 |
0x07 |
S |
0xD5+S |
0x35 |
The response from the gateway will be as follows:
Response:Request HeatSetpoint <address = 1401><setback_state = 2><setpoint = 47>
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
|
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Setback State |
ESC |
Setpoint |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x09 |
0x06 |
0x04 |
0x3F |
0x01 |
0x00 |
0x00 |
0x79 |
0x05 |
0x02 |
0x2F |
0x2F |
0xFD |
0x35 |
Note: The setpoint was 23.5C or 47degE, this corresponds to the escape value (0x2F) of the tpck protocol and therefore must be escaped.
Example 3
Updating the outdoor temperature to 50F, however, there is another device on the network providing a valid outdoor temperature of 48F and so the network will continue to use that temperature until it becomes invalid. The temperature that returned will be 48F. If it is required to make the gateway the outdoor temperature master, remove all other temperature sensors from the tekmarNet network.
The outdoor temperature must be set in degH:
OD = 10H/F * 50F + 850H = 1350H
Update OutdoorTemperature <temperature = 1350>
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x07 |
0x06 |
0x00 |
0x17 |
0x01 |
0x00 |
0x00 |
0x46 |
0x05 |
0x70 |
0x35 |
The response from the gateway will be as follows:
Response:Update OutdoorTemperature <temperature = 1330>
|
Byte Index |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
|
Content |
SOF |
Length |
Type |
Service |
Method[0] |
Method[1] |
Method[2] |
Method[3] |
Address[0] |
Address[1] |
Checksum |
EOF |
|
Hex Value |
0xCA |
0x07 |
0x06 |
0x03 |
0x17 |
0x01 |
0x00 |
0x00 |
0x32 |
0x05 |
0x5F |
0x35 |
Troubleshooting
A terminal shell called Termite can be used to test the RS 232 serial port hexadecimal data. This bypasses the home automation interface and driver when testing operation of the thermostat.
Step 1: Download the Termite (complete setup) terminal program for Windows.
http://www.compuphase.com/software_termite.htm
Step 2: Settings
Baud rate = 9600, Data bits = 8, Stop bits = 1, Parity = none, Flow control = none, Forward = none, Hex View = check marked
Step 3: Enter commands
Hexadecimal values can be entered in the command line at the bottom of the window. The hexadecimal numbers must be entered in the format 0x00 followed by a space. Connect a single thermostat that is manually addressed to 01 to the 482. Commands can be copied from the examples on this web page and pasted into the Termite command line.
