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 Setpoint Control 161 (101101) - 1 Stage Heat
• tekmarNet4 Setpoint Control 162 (101102) - 1 Stage Heat/Cool
• 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
• 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
• tekmarNet Thermostat 532 (107201) - 1 Stage Heat
• tekmarNet Thermostat 552 (105103) - 1 Stage Heat
• tekmarNet Thermostat 553 (105102) - 2 Stage Heat, 1 Stage Cool, 1 Fan, Humidity
• tekmarNet Thermostat 554 (105101) - 1 Stage Heat, 1 Stage Cool, 1 Fan
• tekmarNet Thermostat 557 (104401) - 2 Stage Heat, 2 Stage Cool, 1 Fan, Humidity
• Snow Melting Control 654 (105801)
• Snow Melting Control 670 (108401)
• Snow Melting Control 671 (108402)

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.

• 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

* 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 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.

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

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

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.

* 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.

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.

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.

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:

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:

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:

Copy and paste to Termite: 0xca 0x06 0x06 0x00 0x0f 0x01 0x00 0x00 0x01 0x1d 0x35

To disable reporting:

 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:

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:

To update the outdoor temperature to 80 degree Fahrenheit:

 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:

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:

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
• 0x05 - Not used
• 0x06 - Emergency

Example

To request the mode of thermostat with address 0001:

 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:

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:

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:

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:

 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:

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

• 0x00 - None
• 0x01 - Heat
• 0x03 - Cool

Example

To request the active demands on the thermostat with address 0001:

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:

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:

Copy and paste to Termite: 0xca 0x09 0x06 0x01 0x37 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x49 0x35

The response could be:

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:

Copy and paste to Termite: 0xca 0x09 0x06 0x01 0x38 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x4a 0x35

The response could be:

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:

 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:

 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:

 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%:

Copy and paste to Termite: 0xca 0x09 0x06 0x00 0x57 0x01 0x00 0x00 0x01 0x00 0x07 0x32 0xa1 0x35

The response:request will be:

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:

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:

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:

together with:

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:

Copy and paste to Termite: 0xca 0x06 0x06 0x00 0x6f 0x01 0x00 0x00 0x01 0x7d 0x35

To update to disable setback schedules:

 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:

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:

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. Note: This method only supports thermostats configured to schedule master 1, 2, 3 or 4. Thermostats configured to schedule off, zone, or schedule member 1, 2, 3 or 4 are not supported.

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:

 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.

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.

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:

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:

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:

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:

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:

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.

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

Examples

To enable a device that has setpoint enable ID 1:

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

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

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

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


Update, HumidityMax, Address 0001, 80%

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

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


Update, HumidityMin, Address 0001, 20%

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.

• 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>

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:

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>

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:

The response from the gateway will be as follows:

Response:Request    HeatSetpoint    <address = 1401><setback_state = 2><setpoint = 47> 

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>

The response from the gateway will be as follows:

Response:Update    OutdoorTemperature    <temperature = 1330>

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.