Skip to Main Content
Logo

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.

Protocol Versions

Protocol version 1 - Released in July 2009 with software versions 00 through 125.

Protocol version 2 - Released in July 2013 with software version 137.

Protocol version 3 - Released in January 2017 with software version 154.

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.

Physical Layer

A serial (RS-232) interface is used on the tHA (482) gateway with the following parameters.

The tHA (482) gateway uses a RJ45 connector described below.

RJ45 Male Connector Pin Numbering

homeAutomation

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:

  1. Service
    • The service types identifies the action/direction of the message. There are five service types described below.
  2. Method
    • Specifies the type of data contained in the message.
  3. 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:

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

Included in Protocol Version

NullMethod

0x000

0

None

1

NetworkError

0x107

2

error

1

ReportingEnable

0x10F

1

enable

1

OutdoorTemperature

0x117

2

temperature

1

DeviceAttributes

0x11F

4

address, attributes

1

ModeSetting

0x127

3

address, mode

1

ActiveDemand

0x12F

3

address, demand

1

CurrentTemperature

0x137

4

address, temperature

1

CurrentFloorTemperature 0x138

4

address, temperature

3

HeatSetpoint

0x13F

4

address, setback_state, setpoint

1

CoolSetpoint

0x147

4

address, setback_state, setpoint

1

SlabSetpoint

0x14F

4

address, setback_state, setpoint

1, 3*

FanPercent

0x157

4

address, setback_state, percent

1

TakingAddress

0x15F

4

old_address, new_address

1

DeviceInventory

0x167

2

address

1

SetbackEnable

0x16F

1

enable

1

SetbackState

0x177

3

address, setback_state

1

SetbackEvents

0x17F

3

address, events

1

FirmwareRevision

0x187

2

revision

1

ProtocolVersion

0x18F

2

version

1

DeviceType

0x197

6

address, type

1

DeviceVersion

0x19F

6

address, version

1

DateTime

0x1A7

7

year, month, day, weekday, hour, minute

1

SetpointGroupEnable

0x13D

2

setpoint ID number, enable

2

SetpointDevice

0x13E

2

address, setback_state, setpoint

2

RelativeHumidity

0x150

3

address, humidity

2

HumidityMax

0x151

3

address, humidity

2

HumidityMin

0x152

3

address, humidity

2

* Slab setpoint was availble in prior versions if no room sensor was configured.  With protocol version 3 the slab setpoint message can be used as a slab minimum target temperature when both room and floor sensing is configured.

 

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.

 

Protocol version 1 Update behavior:

An Update message from a home automation system is sent to the Gateway 482, which in turn sends an update message to the thermostat. Once the thermostat updates its setting, it initiates a Response:Update message to the Gateway 482, which in turn sends the Response:Update message to the home automation system. The latency of the Update and Update:Response messages are dependent on the tekmarNet network activity and can range from several seconds to a minute.

482 protocol version 1 update operation 

Protocol version 2 Update behavior:

An Update message from a home automation system is sent to the Gateway 482. The 482 updates its database with the new value and returns a Response:Update message to the home automation system. The 482 then sends the Update message to the thermostat. Once the thermostat updates its setting, it initiates a Response:Update message back to the Gateway 482, which in turns sends a Report to the home automation system.

The protocol version 2 behavior provides feedback to the home automation system within several milliseconds of the 482 receiving the Update message. This improves the home automation system behavior when incrementing or decrementing a temperature, fan or humidity setpoint. A drawback to this is that the 482 may provide a Response:Update message of a setting value that is out of range. Only when Report message is received can the true thermostat setting be known.

482 protocol version 2 update operation

 

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.

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

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

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.

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

Example

To request the mode of 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 0x27 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x39 0x35

 Copy and paste to Termite: 0xca 0x09 0x06 0x01 0x27 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x39 0x35

 

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

To change thermostat with address 0001 to mode emergency:

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 0x06 0x00 0x3e 0x35

Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x27 0x01 0x00 0x00 0x01 0x00 0x06 0x00 0x3e 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

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

 


 

CurrentFloorTemperature

Description

The CurrentFloorTemperature method provides access to the floor temperature (if the floor/slab sensor is configured on the product) 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

0x138

Data

(uint16_t) Address of the device.

(uint16_t) floor temperature in degH (see definitions).

Example

To request the current floor 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 0x38 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x4a 0x35

Copy and paste to Termite: 0xca 0x09 0x06 0x01 0x38 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x4a 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 0x38 0x01 0x00 0x00 0x01 0x00 0x5f 0x06 0xb2 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 floor setpoint for the specified device. In order to support SlabSetpoint, the thermostat must have the floor temperature sensor enabled.

A value of THA_CURRENT = 0x07 may be used to request the current setpoint instead of specifying the actual setback state.  This setpoint applies to Slab only configuration (no room air sensor) or Slab minimum configuration (room air sensing also applies). 

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

Address != 0

Request

Sending an request to the gateway can have to possible effects depending on the value of the address parameter.

Address = 0

Address != 0

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

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

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

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.

 


SetpointGroupEnable

Description

The SetpointGroupEnable enables or disables the specified setpoint group. This allows the enable or disable of the Setpoint Controls 161 and 162, as well as, the Snow Melting Control 654.

Services

Update

When an update is sent to the gateway the setpoint group that matches the id is set to the value of the enable variable.

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 state of the specified setpoint group.

If the device does not support this setting then THA_NA_8 is returned.

Report

A report contains the state of setpoint group.

Method ID

0x13D

Data

(uint8_t) Setpoint Enable ID Number.

Setpoint Enable ID number in decimal Setpoint enable ID number in hexadecimal
1 0x01
2 0x02
3 0x03
4 0x04
5 0x05
6 0x06
7 0x07
8 0x08
9 0x09
10 0x0a
11 0x0b
12 0x0c

(uint8_t) Enable: enable = 0x01, disable = 0x00

Examples

To enable a device that has setpoint enable ID 1:

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 0x3d 0x01 0x00 0x00 0x01 0x01 0x4d 0x35

Copy and paste to Termite: 0xca 0x07 0x06 0x00 0x3d 0x01 0x00 0x00 0x01 0x01 0x4d 0x35

Snow Melting Control Examples

The commands to start and stop the snow melting system are as follows. Please note that the snow melt controls do not report their address because this message is broadcast to the entire tekmarNet communication system. The Snow Melting Control 654 factory default uses Melt Group 1 and Storm Group 12. 

 

To start melting using Melt Group 1:

0xca 0x07 0x06 0x00 0x3d 0x01 0x00 0x00 0x01 0x01 0x4d 0x35

The response is:

0xca 0x07 0x06 0x02 0x3d 0x01 0x00 0x00 0x01 0x01 0x4f 0x35

To stop melting using Melt Group 1:

0xca 0x07 0x06 0x00 0x3d 0x01 0x00 0x00 0x01 0x00 0x4c 0x35

The response is:

0xca 0x07 0x06 0x02 0x3d 0x01 0x00 0x00 0x01 0x00 0x4e 0x35

To poll for the status of Melt Group 1:

0xca 0x07 0x06 0x01 0x3d 0x01 0x00 0x00 0x01 0x00 0x4d 0x35

There are two possible responses:

0xca 0x07 0x06 0x04 0x3d 0x01 0x00 0x00 0x01 0x00 0x50 0x35 = Off

0xca 0x07 0x06 0x04 0x3d 0x01 0x00 0x00 0x01 0x01 0x51 0x35 = Melting

 

To start the storm operation using Storm Group 12:

0xca 0x07 0x06 0x00 0x3d 0x01 0x00 0x00 0x0c 0x01 0x58 0x35

The response is:

0xca 0x07 0x06 0x02 0x3d 0x01 0x00 0x00 0x0c 0x01 0x5A 0x35

To stop the storm operation:

0xca 0x07 0x06 0x00 0x3d 0x01 0x00 0x00 0x0c 0x00 0x57 0x35

The response is:

0xca 0x07 0x06 0x02 0x3d 0x01 0x00 0x00 0x0c 0x00 0x59 0x35

To poll for the status of the storm operation using Storm Group 12:

 0xca 0x07 0x06 0x01 0x3d 0x01 0x00 0x00 0x0c 0x00 0x58 0x35

 There are two possible responses:

 0xca 0x07 0x06 0x04 0x3d 0x01 0x00 0x00 0x0c 0x00 0x5b 0x35 = Off

 0xca 0x07 0x06 0x04 0x3d 0x01 0x00 0x00 0x0c 0x01 0x5c 0x35 = Storm


SetpointDevice

Description

The SetpointDevice method provides access to the setpoint for the specified setpoint device and setback state for the Setpoint Controls 161 and 162.

A value of THA_CURRENT = 0x07 may be used to request the current setpoint instead of specifying the actual setback state.

Service

Update

When an update is sent to the gateway the 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 setpoint of the device.

If the device does not support this setting then THA_NA_8 is returned.

Report

A report contains the specified setpoint of the device.

Method ID

0x13E

Data

(uint16_t) Address of the device.

(uint8_t) Setback state of the device (see definitions for possible values).

(uint16_t) Temperature being targeted in degH (see definitions).

Example

Update SetpointDevice with Address 0001, Current setback state, Change setpoint to 100F

Byte Index 0 1 2 3 4 5 6 7 8 9 10 11 12 14 15
Content SOF Length Type Service Method(0) Method(1) Method(2) Method(3) Data(0) Data(1) Data(2) Data(3)  Data(4) CS EOF
Hex Value 0xca 0x0a 0x06 0x00 0x3e 0x01 0x00 0x00 0x01 0x00 0x07 0x3a 0x07 0x98 0x35

Copy and paste to Termite: 0xca 0x0a 0x06 0x00 0x3e 0x01 0x00 0x00 0x01 0x00 0x07 0x3a 0x07 0x98 0x35

 


RelativeHumidity

Description

The RelativeHumidity method provides access to the relative humidity sensor for the specified device. The range of possible values is 0 to 100%. This is supported on the Thermostats 553 and 557.

Services

Update
Updating the humidity is not a valid operation, no response will be sent.

Request
When a request is received by the gateway it responds by sending a Response:Request containing the current relative humidity of the specified device.

Report
A report contains the current relative humidity of the specified device.

Method ID

0x150

Data

(uint16_t) Address of the device.
(uint8_t) Relative Humidity in 1% increments.

Example

Request, Relative Humidity, 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(2) CS EOF
Hex Value 0xca 0x08 0x06 0x01 0x50 0x01 0x00 0x00 0x01 0x00 0x00 0x61 0x35

Copy and paste to Termite: 0xca 0x08 0x06 0x01 0x50 0x01 0x00 0x00 0x01 0x00 0x00 0x61 0x35

 


HumidityMax

Description

This method is available for a device if the dehumidification attribute is present. The HumidityMax method provides access to the maximum relative humidity (dehumidification) setpoint for the specified device. The range of possible values is 20 to 80%. 0% means that dehumidification is off. This is supported on the Thermostats 553 and 557.

Services

Update
When an update is sent to the gateway the humidity max of the specified device 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. If the setpoint is out of range it may be limited by the device.

Request
When a request is received by the gateway it responds by sending a Response:Request containing the current humidity max of the specified device.

Report
A report contains the humidity max of the specified device.

Method ID

0x151

Data

(uint16_t) Address of the device.

(uint8_t) Humidity Max in 1% increments.

Examples

Request, HumidityMax, 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(2) CS EOF
Hex Value 0xca 0x08 0x06 0x01 0x51 0x01 0x00 0x00 0x01 0x00 0x00 0x62 0x35

Copy and paste to Termite: 0xca 0x08 0x06 0x01 0x51 0x01 0x00 0x00 0x01 0x00 0x00 0x62 0x35


Update, HumidityMax, Address 0001, 80%

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(2) CS EOF
Hex Value 0xca 0x08 0x06 0x00 0x51 0x01 0x00 0x00 0x01 0x00 0x50 0xb1 0x35

Copy and paste to Termite: 0xca 0x08 0x06 0x00 0x51 0x01 0x00 0x00 0x01 0x00 0x50 0xb1 0x35

 


 

HumidityMin

Description

This method is available for a device if the humidification attribute is present. The HumidityMin method provides access to the minimum relative humidity (humidification) setpoint for the specified device. The range of possible values is 20 to 80%. 0% means that humidification is off. This is supported on the Thermostats 553 and 557.

Services

Update

When an update is sent to the gateway the humidity min of the specified device 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. If the setpoint is out of range it may be limited by the device.

Request

When a request is received by the gateway it responds by sending a Response:Request containing the current humidity min of the specified device.

Report

A report contains the humidity min of the specified device.

Method ID

0x152

Data

(uint16_t) Address of the device.

(uint8_t) Humidity Min 1% increments.

Examples

Request, HumidityMin, 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(2) CS EOF
Hex Value 0xca 0x08 0x06 0x01 0x52 0x01 0x00 0x00 0x01 0x00 0x00 0x63 0x35

Copy and paste to Termite: 0xca 0x08 0x06 0x01 0x52 0x01 0x00 0x00 0x01 0x00 0x00 0x63 0x35


Update, HumidityMin, Address 0001, 20%

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(2) CS EOF
Hex Value 0xca 0x08 0x06 0x00 0x52 0x01 0x00 0x00 0x01 0x00 0x14 0x76 0x35

Copy and paste to Termite: 0xca 0x08 0x06 0x00 0x52 0x01 0x00 0x00 0x01 0x00 0x14 0x76 0x35

 


 

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.

Not Applicable or Invalid Values

Values used to indicate an unknown or undefined quantity.

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.

Termite Termite Settings Termite CommandLine

0xca 0x08 0x06 0x01 0x2f 0x2f 0x01 0x00 0x00 0x01 0x00 0x00 0x40 0x35