kanmor Home Automation Protocol PDF Print

Description

The kanmor 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

kanmor'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

The device type accessible through the DeviceType method is listed in brackets.

  • tekmarNet4 Gateway 482e - Serial Interface
  • tekmarNet4 Thermostat 537e (100102) - 1 Stage Heat
  • tekmarNet4 Thermostat 538e (100103) - 1 Stage Heat
  • tekmarNet4 Thermostat 540e (100101) - 1 Stage Heat, 1 Stage Cool, 1 Fan
  • tekmarNet4 Thermostat 542e (99302) - 1 Stage Heat
  • tekmarNet4 Thermostat 546e (99201) - 2 Stage Heat, 2 Stage Cool, 2 Fan

Protocol Stack

The tHA protocol has three layers, stating at the physical layer, the tHA 482 gateway uses RS-232 for communicating with the home automation network. The middle layer is the kanmor 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 kanmor-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

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

kanmor Packet Protocol

Description

The kanmor 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.

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

  • Update - Indicates that the data associated with the method is to be updated.

  • Request - Indicates that the data associated with the method is desired.

  • Report - Indicates that the data in the message is that associated with the method.

  • Response:Update - Is sent in response to an update and contains the accepted value(s).

  • Response:Request - Is sent in response to an request and contains the requested data.

A table of available commands is listed below, for more detail on specific methods please refer to the tHA Method Descriptions.

Method Name

Method ID

Data Size (Bytes)

Data Parameters

NullMethod

0x000

0

None

NetworkError

0x107

2

error

ReportingEnable

0x10F

1

enable

OutdoorTemperature

0x117

2

temperature

DeviceAttributes

0x11F

4

address, attributes

ModeSetting

0x127

3

address, mode

ActiveDemand

0x12F

3

address, demand

CurrentTemperature

0x137

4

address, temperature

HeatSetpoint

0x13F

4

address, setback_state, setpoint

CoolSetpoint

0x147

4

address, setback_state, setpoint

SlabSetpoint

0x14F

4

address, setback_state, setpoint

FanPercent

0x157

4

address, setback_state, percent

TakingAddress

0x15F

4

old_address, new_address

DeviceInventory

0x167

2

address

SetbackEnable

0x16F

1

enable

SetbackState

0x177

3

address, setback_state

SetbackEvents

0x17F

3

address, events

FirmwareRevision

0x187

2

revision

ProtocolVersion

0x18F

2

version

DeviceType

0x197

6

address, type

DeviceVersion

0x19F

6

address, version

DateTime

0x1A7

7

year, month, day, weekday, hour, minute

tHA Protocol Diagram

The tHA protocol diagram is the tpck and tRPC protocols combined.

Byte Index

0

1

2

3

4 - 7

8 - 8+N-1

8+N

9+N

Content

SOF

Length

Type

Service

Method

Data

Checksum

EOF

tHA Service Descriptions

The following services are sent to the tHA gateway:

Update

When an Update is sent to the tHA gateway the data associated with the specific command is updated with the supplied values. A Response:Request is then sent from the tHA gateway containing the accepted values, which may differ from the values sent. If a Response:Update is not received two minutes after this message was sent the update should be considered timed out; however, it is still possible that the gateway will send a response.

Request

When a Request is sent to the tHA gateway the data associated with the specified command is returned in Response:Request message.

The following services are sent from the tHA gateway:

Response:Update

This message is sent from the tHA gateway in response to an Update command, the accepted values for the updated parameters are contained in this message. If a Response:Update is not received two minutes after this message was sent the update should be considered timed out; however, it is still possible that the gateway will send a response.

Response:Request

This message is sent from the tHA gateway in response to a Request command, the data associated with the requested command is contained in this message.

Report

This message contains the same information as a Response:Request but is unsolicited, these messages may be turned on or off with the ReportingEnable command.

tHA Method Descriptions

NullMethod

Description

A Null message. This message will be sent if an unsupported method is received by the gateway device.

Method ID

0x000

Data

None

NetworkError

Description

Current network (tekmarNet) error, this will be non-zero if there is an error present on the network.

Services

Update

Updating the network error a valid operation, the gateway will respond by sending a Response:Update containing the current network error.

Request

When a request is received the gateway device responds by sending Response:Request containing the current network error.

Report

Contains the current network error.

Method ID

0x107

Data

(uint16_t) The current network error, non-zero value indicates an error is present.


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.

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.


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

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

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

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


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


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.


SlabSetpoint

Description

The SlabSetpoint 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 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.


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 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 10% increments.


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.


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.


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.

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

SetbackEvents

Description

The SetbackEvents method provides access to the number of setback events for the specified device. This is either zero (no schedule), two events, or four events.

Services

Update

Updating the setback events parameter is not a supported operation, the gateway will respond by sending a Response:Update containing the current value of the setback events parameter.

Request

When a Request is received by the gateway it responds by sending a Response:Request containing the setback events configuration of the specified device.

Report

A Report contains the setback events configuration of the specified device.

Method ID

0x17F

Data

(uint16_t) Address of the device.

(uint8_t) Setback events

  • 0x00 - Zero events, no schedule is running.
  • 0x01 - Two events (Occ, UnOcc). This is a commercially-oriented schedule intended for buildings that are cycle between occupied and unoccupied only once per day.

  • 0x02 - Four events (Wake, UnOcc, Occ, Sleep). This is a typical residential schedule configuration that allows for a range of household occupancy cycling patterns.


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.


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.


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.


DeviceVersion

Description

The DeviceVersion method provides access to the software 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.


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

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

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

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

 

N/A Values

Values used to indicate an unknown or undefined quantity.

  • THA_NA_8 = 0xFF
  • THA_NA_16 = 0xFFFF
  • THA_NA_32 = 0xFFFFFFFF

Examples

I this examples of sending requests/updates and receiving the responses will be given.

Example 1

Requesting the complete device inventory (all supported devices on the network). In this example there are two devices on the network with address = 0001 and address = 0002.

Service - Request (0x01)

Method - DeviceInventory (0x167)

Data - address = 0

or for the future written as:

Request    DeviceInventory    <address = 0000>

Byte Index

0

1

2

3

4

5

6

7

8

9

10

11

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Checksum

EOF

Hex Value

0xCA

0x07

0x06

0x01

0x67

0x01

0x00

0x00

0x00

0x00

0x76

0x35

The checksum is calculated as the sum of the length field, the type field, and all the data bytes ignoring 8-bit overflows (modulo 256).

CS = 0x07 + 0x06 + 0x01 + 0x67 + 0x01 + 0x00 + 0x00 + 0x00 + 0x00 = 0x76

The response from the gateway will be as follows:

Response:Request    DeviceInventory    <address = 0001>
Response:Request DeviceInventory <address = 0002>
Response:Request DeviceInventory <address = 0000> - Indicates that listing the device inventory is complete.

The byte stream for the first response is as follows:

Byte Index

0

1

2

3

4

5

6

7

8

9

10

11

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Checksum

EOF

Hex Value

0xCA

0x07

0x06

0x04

0x67

0x01

0x00

0x00

0x01

0x00

0x7A

0x35

Example 2

Requesting the current heat setpoint from the device with address = 1401.

We will assume that device 1401 is in the OCC_4 state and has a setpoint of 74F or approx. 23.5C (47degE).

Request    HeatSetpoint    <address = 1401><setback_state = THA_CURRENT>

Byte Index

0

1

2

3

4

5

6

7

8

9

10

11

12

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Setback State

Checksum

EOF

Hex Value

0xCA

0x08

0x06

0x01

0x3F

0x01

0x00

0x00

0x79

0x05

0x07

0xD4

0x35

A setpoint could also be sent in the request and it would still be valid, the gateway will simply ignore it; therefore, the following byte stream would also be valid:

Byte Index

0

1

2

3

4

5

6

7

8

9

10

11

12

13

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Setback State

Setpoint

Checksum

EOF

Hex Value

0xCA

0x09

0x06

0x01

0x3F

0x01

0x00

0x00

0x79

0x05

0x07

S

0xD5+S

0x35

The response from the gateway will be as follows:

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

Byte Index

0

1

2

3

4

5

6

7

8

9

10

 

11

12

13

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Setback State

ESC

Setpoint

Checksum

EOF

Hex Value

0xCA

0x09

0x06

0x04

0x3F

0x01

0x00

0x00

0x79

0x05

0x02

0x2F

0x2F

0xFD

0x35

Note: The setpoint was 23.5C or 47degE, this corresponds to the escape value (0x2F) of the tpck protocol and therefore must be escaped.

Example 3

Updating the outdoor temperature to 50F, however, there is another device on the network providing a valid outdoor temperature of 48F and so the network will continue to use that temperature until it becomes invalid. The temperature that returned will be 48F. If it is required to make the gateway the outdoor temperature master, remove all other temperature sensors from the tekmarNet network.

The outdoor temperature must be set in degH:

OD = 10H/F * 50F + 850H = 1350H

Update    OutdoorTemperature    <temperature = 1350>

Byte Index

0

1

2

3

4

5

6

7

8

9

10

11

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Checksum

EOF

Hex Value

0xCA

0x07

0x06

0x00

0x17

0x01

0x00

0x00

0x46

0x05

0x70

0x35

The response from the gateway will be as follows:

Response:Update    OutdoorTemperature    <temperature = 1330>

Byte Index

0

1

2

3

4

5

6

7

8

9

10

11

Content

SOF

Length

Type

Service

Method[0]

Method[1]

Method[2]

Method[3]

Address[0]

Address[1]

Checksum

EOF

Hex Value

0xCA

0x07

0x06

0x03

0x17

0x01

0x00

0x00

0x32

0x05

0x5F

0x35