Home Automation, Inc. Omni-Link. Serial Protocol Description

Transcription

1 Home Automation, Inc. Omni-Link Serial Protocol Description This document contains the intellectual property of Home Automation, Inc. (HAI). HAI authorizes the use of this information for the sole purpose of developing software and systems to work with HAI's Serial Interface. The specifications in this document are subject to change without notice. Document Number 10P17 Rev H September 2004

2

3 GENERAL This document defines the Omni-Link communications protocol. This protocol allows an external device to communicate with a Home Automation, Inc. automation controller through an RS-232 or RS-485 serial interface. Omni-Link allows the external device to monitor the status of the HAI controller and to control its operation. The current status of the security system and of each security zone, control unit, temperature sensor, thermostat, and displayed text messages may be obtained. Commands may be sent to control security, units, temperature setpoints, and thermostat operation. Additionally, the controller display names may be uploaded from and downloaded to the HAI controller and the event log may be uploaded from the HAI controller. ELECTRICAL INTERFACE The external device connects to the HAI controller in one of the following manners: a) Through the HAI Model 10A17-1 Serial Interface connected to an OmniLT, Omni, Omni II, OmniPro, or OmniPro II controller. This interface provides both an RS-232 interface and an RS-485 interface. Only one of these interfaces may be active at a time. The RS-232 interface is provided through a standard DB-9M connector. The serial interface may be connected to a personal computer using a readily available "null modem" or data transfer cable. The RS-485 interface is provided through a two-position terminal block. b) Through the serial interface built onto the OmniLT, Omni II, or OmniPro II controller. The serial interface supports both RS-232 and RS-485 connections. The RS-232 interface is provided through a modular connector on the controller. To access the RS-232 interface, use the HAI Model 21A05-2 Serial Cable Kit. Plug one end of the cable into the modular connector on the controller. Plug the other end into the Model 21A05-1 Serial Cable Adapter (modular to DB-9 RS- 232), which connects the controller's serial port to the computer's DB-9 RS-232 port. The RS-485 interface is provided through the same modular connector. To select RS-485, move the interface jumper (below the modular connector) from the "232" to the "485" position. Using a standard 4 position phone cable, use the Yellow and Green wires for communications. The RS-232 interface is configured as DTE (data terminal equipment). This is the same configuration as provided on a typical personal computer. The RS-485 interface may be connected to the external device up to 1000 feet away when using standard twisted pair cabling. Since the RS-485 interface is a half-duplex bus, the external device must be capable of turning its RS-485 driver on before transmitting to the controller and turning it off after it has completed its transmission to the controller. Data is transmitted asynchronously using standard nonreturn-to-zero (NRZ) format (one start bit, eight data bits, and a single stop bit) at up to 9600 baud. Page 1

4 MESSAGE TIMING The Omni-Link protocol is a master/slave protocol. The external device is the master. The HAI controller is the slave. The master initiates all communications. The slave can only communicate when requested by the master. All communication takes place half-duplex. That is, the master will first transmit to the slave, then the slave may reply to the master. Data transfer between the external device and the HAI controller takes place though a series of message exchanges. The external device sends a message to the controller requesting the controller to take some action or to provide some information. The controller then replies with the requested information or an acknowledgement that it has performed the desired action. When using the RS-485 interface, the master must turn on its RS-485 driver, send its message, then disable its RS- 485 driver after the last character of the message has been transmitted. The master's driver must be turned off and the master must be ready to receive the slave's reply within 1 ms after the last character has been transmitted. The master must allow at least 1 second for the slave to begin replying with its message. It must then allow at least 50 ms for each subsequent character to be sent. The master must wait at least 1 ms after receiving the last character from the slave before turning on its driver again to initiate a new message. MESSAGE FORMAT The Omni-Link protocol is a binary protocol. That is, one byte of data is sent as a single character whose hex value is 0x00 through 0xFF. Messages in the Omni-Link protocol can use either the addressable format or the non-addressable format. Any HAI controller that supports the Omni-Link protocol can use the non-addressable format. The nonaddressable format allows only one master device and one HAI controller on the communication link. Some HAI controllers support the addressable format in addition to the non-addressable format. These controllers can be used in the non-addressable mode as described in the preceding paragraph. They can also be used in the addressable mode, so that multiple HAI controllers can be multi-dropped on the same RS-485 communication link. In this mode, each controller is assigned an address that is unique to the communication link. Every controller on the shared communication link receives all messages transmitted by the master device. The controller ignores any message whose address value does not match it s own address. The HAI controller will always recognize messages in the non-addressable format, even if it has been configured with an address for use with the addressable mode. Of course, messages in the non-addressable format should never be transmitted on a multi-dropped communication link, since all of the controllers will react to the message and the replies will collide. The general format of a non-addressable message is as follows: Field Length Comments Start character 1 byte Value is always 0x5A Message length 1 byte Value is the total number of bytes in the message type and data fields 1 byte Value indicates the specific function of the message Data variable Zero or more bytes, depending on the specific message type 1 byte Least-significant-byte of 16-bit CRC 1 byte Most-significant-byte of 16-bit CRC Page 2

5 The general format of an addressable message is as follows: Field Length Comments Start character 1 byte Value is always 0x41 Address 1 byte Must be within range of 0x01 to 0xFE, inclusive Message length 1 byte Value is the total number of bytes in the message type and data fields 1 byte Value indicates the specific function of the message Data none Zero or more bytes, depending on the specific message type 1 byte Least-significant-byte of 16-bit CRC 1 byte Most-significant-byte of 16-bit CRC The CRC-16 error detection algorithm is used to provide a robust error detection capability in the Omni-Link protocol. The CRC1 and CRC2 error check bytes are the 16-bit CRC-16 polynomial remainder, sent leastsignificant-bit first. The CRC value is calculated using all bytes of the message, except the start character and the CRC fields. Sample routines to calculate the CRC-16 error check bytes are provided in Appendix A. MESSAGE TYPES Different message types are provided in the Omni-Link protocol to perform different actions. These message types can be divided into several groups: Acknowledgement messages Access control messages Status request messages Status report messages System event messages Command messages Name messages Event log messages Validate security code messages Please note that in the following sections describing the various message types, only the non-addressable message format is shown. The corresponding message in the addressable format would have the following differences: Start character would be 0x41 Address byte would be inserted immediately following start character CRC value would be different, since address byte must be included in CRC-16 calculation Page 3

6 ACKNOWLEDGEMENT MESSAGES Acknowledgement messages are sent to acknowledge the receipt of another message. An ACKNOWLEDGE message is sent in response to another message to indicate that the message was received correctly and processed. A NEGATIVE ACKNOWLEDGE message is sent in response to another message to indicate that the message was received correctly, but was not processed due to an error in the message format or to an inability to successfully perform the requested action. ACKNOWLEDGE Start character Message length Data 0x5A 0x01 0x05 none 0xC1 0x93 NEGATIVE ACKNOWLEDGE Start character Message length Data 0x5A 0x01 0x06 none 0x81 0x92 ACCESS CONTROL MESSAGES Access control messages are used to insure that only authorized users may access the HAI controller through the Omni-Link interface. The external device must first "log in" using an approved security code before access is allowed to the HAI controller. It may then "log out" when the access has been completed. Once logged in, the external device has full access to the controller. Therefore, only the PC access code or a master code may be used to access the controller through Omni-Link. The external device "logs in" by sending a LOGIN message containing an approved security code. The controller will reply with an ACKNOWLEDGE message if the login was successful. Prior to login, the controller will send NEGATIVE ACKNOWLEDGE messages in reply to all other messages. The ACKNOWLEDGE message can be used to determine if the external device is currently logged in. The controller will reply to an ACKNOWLEDGE message with another ACKNOWLEDGE message if the external device is logged in. The controller will reply with a NEGATIVE ACKNOWLEDGE message if the external device is not logged in. The controller will disallow any further login attempts for one hour if three consecutive unsuccessful login attempts are made. This prevents an intruder from randomly trying all possible security codes to gain access to the controller. Page 4

7 The external device "logs out" by sending a LOGOUT message. This allows the Omni-Link interface to be secured when the external device has completed access to the controller. The system will automatically log the external device out if: No messages are sent for three minutes Carrier detect is lost when using a modem The controller is reset LOGIN Start character Message length Data 2 Data 3 Data 4 0x5A 0x05 0x20 first digit of code second digit of code third digit of code fourth digit of code Each of the digits of the security code must be sent as the numeric value of the digit, 0x00 through 0x09. LOGOUT Start character Message length Data 0x5A 0x01 0x21 none 0xC1 0x88 STATUS REQUEST MESSAGES Status request messages are sent by the external device to the HAI controller to request that the controller report certain status information. The following information can be requested: System information System status Zone status Unit status Auxiliary status Thermostat status Message Status Page 5

8 REQUEST SYSTEM INFORMATION This message requests the HAI controller to report its model number, software version, and local phone number. Start character Message length Data Expected reply 0x5A 0x01 0x11 none 0xC1 0x9C SYSTEM INFORMATION REQUEST SYSTEM STATUS This message requests the HAI controller to report its time, date, calculated time of sunrise and sunset, battery reading, current security mode for each area, and the status of each expansion enclosure. The status for each expansion enclosure includes the AC power status, battery status, communications status, and battery reading. Start character Message length Data Expected reply 0x5A 0x01 0x13 none 0x40 0x5D SYSTEM STATUS REQUEST ZONE STATUS This message requests the HAI controller to report the status of a group of security zones. The status reported for each zone includes the current condition of the zone (secure, not ready, or trouble), the latched alarm status for the zone, whether the zone is armed, whether the zone has had any trouble, and the current analog loop reading for the zone. Start character Message length Data 2 Expected reply 0x5A 0x03 0x15 starting zone ending zone ZONE STATUS Page 6

9 REQUEST UNIT STATUS This message requests the HAI controller to report the status of a group of units. The status reported for each unit includes the unit's current condition and any time remaining on a timed command. If both the starting and ending unit numbers are less than 256, the request is sent using one byte for each unit number: Start character Message length Data 2 Expected reply 0x5A 0x03 0x17 starting unit ending unit UNIT STATUS If either of the unit numbers is 256 or greater, the request is sent using two bytes for each unit number: Start character Message length Data 2 Data 3 Data 4 Expected reply 0x5A 0x05 0x17 starting unit (MSB) starting unit (LSB) ending unit (MSB) ending unit (LSB) UNIT STATUS REQUEST AUXILIARY STATUS This message requests the HAI controller to report the status of a group of temperature sensors. The status reported for each temperature sensor includes: the output relay status for Programmable Energy Saver Modules (PESMs), the current temperature reading, and the low and high temperature setpoints. Start character Message length Data 2 Expected reply 0x5A 0x03 0x19 starting temperature sensor ending temperature sensor AUXILIARY STATUS Page 7

10 REQUEST THERMOSTAT STATUS This message requests the HAI controller to report the status of a group of thermostats. The status reported for each thermostat includes whether the thermostat is communicating with the controller, whether a freeze condition has been detected by the thermostat, the current temperature, the heat and cool setpoints, the system mode, the fan mode, and whether the thermostat has been placed in hold mode. Start character Message length Data 2 Expected reply 0x5A 0x03 0x1E starting thermostat ending thermostat THERMOSTAT STATUS REQUEST MESSAGE STATUS This message requests the HAI controller to report the status of displayed text messages. The status reported for each message includes which messages are currently being displayed and what displayed messages have not been acknowledged. The status reported also indicates if there is a memo message that has not yet been played. Start character Message length Data 0x5A 0x01 0x24 none 0x01 0x8B STATUS REPORT MESSAGES Status report messages are sent in response to each of the status request messages. The following information is reported: System information System status Zone status Unit status Auxiliary status Thermostat status Message status Page 8

11 SYSTEM INFORMATION This message is sent by the HAI controller in reply to a REQUEST SYSTEM INFORMATION message. The controller reports its model number, software version, and local phone number. Start character Message length Data 2 Data 3 Data 4 Data x5A 0x1E 0x12 model number major version minor version revision local phone number The model number identifies the controller model, such as OmniLT, Omni, Omni II, OmniPro, or OmniPro II. The following model numbers are defined: NUMBER MODEL 9 HAI OmniLT 2 HAI Omni 15 HAI Omni II 4 HAI OmniPro 16 HAI OmniPro II The major version, minor version, and revision identify the controller software version. For example, if the software version is 1.4G, the major version would be 0x01, the minor version would be 0x04, and the revision would be 0x07. Revision 0x00 specifies no revision letter, revision 0x01 specifies revision A, and so on. If the revision is a 2's complement negative number, such as 0xFF, it specifies a prototype revision such as X1 or X2. Revision 0xFF specifies revision X1, revision 0xFE specifies revision X2, and so on. The local phone number corresponds to the "MY PHONE NUMBER" setting in the controller. It is an ASCII text string up to 24 characters long, terminated with a trailing 0x00. SYSTEM STATUS This message is sent by the HAI controller in reply to a REQUEST SYSTEM STATUS message. The controller reports its time, date, calculated time of sunrise and sunset, battery reading, current security mode for each area, and the status of each expansion enclosure. The status for each expansion enclosure includes the AC power status, battery status, communications status, and battery reading. Page 9

12 For HAI OmniLT, the reply is as follows: Start character 0x5A Message length 0x10 0x14 time/date valid flag Data 2 year (0-99) Data 3 month (1-12) Data 4 day (1-31) Data 5 day of week (1-7) Data 6 hour (0-23) Data 7 minute (0-59) Data 8 second (0-59) Data 9 daylight savings time flag 0 calculated sunrise hour (0-23) 1 calculated sunrise minute (0-59) 2 calculated sunset hour (0-23) 3 calculated sunset minute (0-59) 4 battery reading 5 security mode For HAI Omni and HAI Omni II, the reply is as follows: Start character 0x5A Message length 0x11 0x14 time/date valid flag Data 2 year (0-99) Data 3 month (1-12) Data 4 day (1-31) Data 5 day of week (1-7) Data 6 hour (0-23) Data 7 minute (0-59) Data 8 second (0-59) Data 9 daylight savings time flag 0 calculated sunrise hour (0-23) 1 calculated sunrise minute (0-59) 2 calculated sunset hour (0-23) 3 calculated sunset minute (0-59) 4 battery reading 5 area 1 security mode 6 area 2 security mode Page 10

13 For HAI OmniPro, the reply is as follows: Start character 0x5A Message length 0x1F 0x14 time/date valid flag Data 2 year (0-99) Data 3 month (1-12) Data 4 day (1-31) Data 5 day of week (1-7) Data 6 hour (0-23) Data 7 minute (0-59) Data 8 second (0-59) Data 9 daylight savings time flag 0 calculated sunrise hour (0-23) 1 calculated sunrise minute (0-59) 2 calculated sunset hour (0-23) 3 calculated sunset minute (0-59) 4 battery reading 5 area 1 security mode 6 area 2 security mode 7 area 3 security mode 8 area 4 security mode 9 area 5 security mode Data 20 area 6 security mode Data 21 area 7 security mode Data 22 area 8 security mode Data 23 expansion enclosure 1 status Data 24 expansion enclosure 1 battery reading Data 25 expansion enclosure 2 status Data 26 expansion enclosure 2 battery reading Data 27 expansion enclosure 3 status Data 28 expansion enclosure 3 battery reading Data 29 expansion enclosure 4 status Data 30 expansion enclosure 4 battery reading Page 11

14 For HAI OmniPro II, the reply is as follows: Start character 0x5A Message length 0x27 0x14 time/date valid flag Data 2 year (0-99) Data 3 month (1-12) Data 4 day (1-31) Data 5 day of week (1-7) Data 6 hour (0-23) Data 7 minute (0-59) Data 8 second (0-59) Data 9 daylight savings time flag 0 calculated sunrise hour (0-23) 1 calculated sunrise minute (0-59) 2 calculated sunset hour (0-23) 3 calculated sunset minute (0-59) 4 battery reading 5 area 1 security mode 6 area 2 security mode 7 area 3 security mode 8 area 4 security mode 9 area 5 security mode Data 20 area 6 security mode Data 21 area 7 security mode Data 22 area 8 security mode Data 23 expansion enclosure 1 status Data 24 expansion enclosure 1 battery reading Data 25 expansion enclosure 2 status Data 26 expansion enclosure 2 battery reading Data 27 expansion enclosure 3 status Data 28 expansion enclosure 3 battery reading Data 29 expansion enclosure 4 status Data 30 expansion enclosure 4 battery reading Data 31 expansion enclosure 5 status Data 32 expansion enclosure 5 battery reading Data 33 expansion enclosure 6 status Data 34 expansion enclosure 6 battery reading Data 35 expansion enclosure 7 status Data 36 expansion enclosure 7 battery reading Data 37 expansion enclosure 8 status Data 38 expansion enclosure 8 battery reading The time/date valid flag is zero if the time and date have not been set in the controller. The daylight savings time flag is nonzero if daylight savings time is in effect. The day of the week is 1 for Monday through 7 for Sunday. Page 12

15 The security mode for an area is as follows: 0 Off 1 Day 2 Night 3 Away 4 Vacation 5 Day instant 6 Night delayed The bits in the expansion enclosure status bytes are shown below. The corresponding bit is set if the condition is true. Bit 0 Bit 1 Bit 7 AC power off Battery low Communications failure ZONE STATUS This message is sent by the HAI controller in reply to a REQUEST ZONE STATUS message. The controller reports the status of a group of security zones. The status reported for each zone includes the current condition of the zone (secure, not ready, or trouble), the latched alarm status for the zone, whether the zone is armed, whether the zone has had any trouble, and the current analog loop reading for the zone. Start character 0x5A Message length (2 * number of zones) + 1 0x16 zone status for first zone Data 2 analog loop reading for first zone Data 3 zone status for second zone Data 4 analog loop reading for second zone... Data n-1 zone status for last zone Data n analog loop reading for last zone The zone status for a zone is packed into a single byte. Bits 0 and 1 indicate the current condition of the zone: Bit 1 Bit 0 Current Condition 0 0 Secure 0 1 Not ready 1 0 Trouble Bits 2 and 3 indicate the latched alarm status for the zone: Bit 3 Bit 2 Latched Alarm Status 0 0 Secure 0 1 Tripped 1 0 Reset, but previously tripped Page 13

16 Bits 4 and 5 indicate the arming status for the zone: Bit 5 Bit 4 Arming Status 0 0 Disarmed 0 1 Armed 1 0 Bypassed by user 1 1 Bypassed by system Bit 6 is set if a trouble condition has occurred that has not been acknowledged by the user. The current condition of the zone will indicate whether the zone currently has a trouble condition. If the zone does not currently have a trouble condition, but bit 6 is set, it indicates that the zone has previously had a trouble condition that has not yet been acknowledged. Status can be requested for the following zones in HAI OmniLT: Zone 1-25 Zone 26 Zone 27 Zone 28 Zone 29 Zone 30 Zone 31 Zone 32 Zone 33 Zone 34 Zone 35 Zone 36 Security zone inputs Freeze alarm Fire emergency Police emergency Auxiliary emergency Duress alarm Battery low trouble AC power failure trouble Phone line dead trouble Digital communicator trouble Fire tamper trouble Fuse trouble Status can be requested for the following zones in HAI Omni: Zone 1-32 Zone 33 Zone 34 Zone 35 Zone 36 Zone 37 Zone 38 Zone 39 Zone 40 Zone 41 Zone 42 Zone 43 Zone 44 Zone 45 Security zone inputs Freeze alarm Area 1 fire emergency Area 2 fire emergency Area 1 police emergency Area 2 police emergency Area 1 auxiliary emergency Area 2 auxiliary emergency Area 1 duress alarm Area 2 duress alarm Battery low trouble AC power failure trouble Phone line dead trouble Digital communicator trouble Status can be requested for the following zones in HAI Omni II: Zone 1-48 Zone 49 Zone 50 Zone 51 Zone 52 Zone 53 Security zone inputs Freeze alarm Area 1 fire emergency Area 2 fire emergency Area 1 police emergency Area 2 police emergency Page 14

17 Zone 54 Zone 55 Zone 56 Zone 57 Zone 58 Zone 59 Zone 60 Zone 61 Zone 62 Zone 63 Area 1 auxiliary emergency Area 2 auxiliary emergency Area 1 duress alarm Area 2 duress alarm Battery low trouble AC power failure trouble Phone line dead trouble Digital communicator trouble Fire tamper trouble Fuse trouble Status can be requested for the following zones in HAI OmniPro: Zone 1-96 Zone 97 Zone 98 Zone 99 Zone 100 Zone 101 Zone 102 Zone 103 Zone 104 Zone 105 Zone 106 Zone 107 Zone 108 Zone 109 Zone 110 Zone 111 Zone 112 Zone 113 Zone 114 Zone 115 Zone 116 Zone 117 Zone 118 Zone 119 Zone 120 Zone 121 Zone 122 Zone 123 Zone 124 Zone 125 Zone 126 Zone 127 Zone 128 Zone 129 Zone 130 Zone 131 Zone 132 Zone 133 Security zone inputs Freeze alarm Area 1 fire emergency Area 2 fire emergency Area 3 fire emergency Area 4 fire emergency Area 5 fire emergency Area 6 fire emergency Area 7 fire emergency Area 8 fire emergency Area 1 police emergency Area 2 police emergency Area 3 police emergency Area 4 police emergency Area 5 police emergency Area 6 police emergency Area 7 police emergency Area 8 police emergency Area 1 auxiliary emergency Area 2 auxiliary emergency Area 3 auxiliary emergency Area 4 auxiliary emergency Area 5 auxiliary emergency Area 6 auxiliary emergency Area 7 auxiliary emergency Area 8 auxiliary emergency Area 1 duress alarm Area 2 duress alarm Area 3 duress alarm Area 4 duress alarm Area 5 duress alarm Area 6 duress alarm Area 7 duress alarm Area 8 duress alarm Battery low trouble AC power failure trouble Phone line dead trouble Digital communicator trouble Page 15

18 Status can be requested for the following zones in HAI OmniPro II: Zone Zone 177 Zone 178 Zone 179 Zone 180 Zone 181 Zone 182 Zone 183 Zone 184 Zone 185 Zone 186 Zone 187 Zone 188 Zone 189 Zone 190 Zone 191 Zone 192 Zone 193 Zone 194 Zone 195 Zone 196 Zone 197 Zone 198 Zone 199 Zone 200 Zone 201 Zone 202 Zone 203 Zone 204 Zone 205 Zone 206 Zone 227 Zone 208 Zone 209 Zone 210 Zone 211 Zone 212 Zone 213 Zone 214 Zone 215 Security zone inputs Freeze alarm Area 1 fire emergency Area 2 fire emergency Area 3 fire emergency Area 4 fire emergency Area 5 fire emergency Area 6 fire emergency Area 7 fire emergency Area 8 fire emergency Area 1 police emergency Area 2 police emergency Area 3 police emergency Area 4 police emergency Area 5 police emergency Area 6 police emergency Area 7 police emergency Area 8 police emergency Area 1 auxiliary emergency Area 2 auxiliary emergency Area 3 auxiliary emergency Area 4 auxiliary emergency Area 5 auxiliary emergency Area 6 auxiliary emergency Area 7 auxiliary emergency Area 8 auxiliary emergency Area 1 duress alarm Area 2 duress alarm Area 3 duress alarm Area 4 duress alarm Area 5 duress alarm Area 6 duress alarm Area 7 duress alarm Area 8 duress alarm Battery low trouble AC power failure trouble Phone line dead trouble Digital communicator trouble Fire tamper trouble Fuse trouble Page 16

19 UNIT STATUS This message is sent by the HAI controller in reply to a REQUEST UNIT STATUS message. The controller reports the status of a group of control units. The status reported for each unit includes the unit's current condition and any time remaining on a timed command. Start character 0x5A Message length (3 * number of units) + 1 0x18 current condition of first unit Data 2 high byte of time for first unit Data 3 low byte of time for first unit Data 4 current condition of second unit Data 5 high byte of time for second unit Data 6 low byte of time for second unit... Data n-2 current condition of last unit Data n-1 high byte of time for last unit Data n low byte of time for last unit The current condition of the unit depends on the type of the unit. For X-10 units, the possible conditions are: 0 Last commanded off 1 Last commanded on Last commanded dim 1-9, respectively Last commanded brighten 1-9, respectively Last commanded level 0%-100%, respectively For Lightolier Compose PLC units: 0 Off 1 On 2-13 Scene A-L, respectively Last commanded dim 1-9, respectively Last commanded brighten 1-9, respectively For Advanced Lighting Control (ALC) relay modules: 0 Off 1 On For Advanced Lighting Control (ALC) dimmer modules: 0 Off 1 On Level 0%-100%, respectively For Universal Powerline Bus (UPB) units: 0 Off 1 On Level 0%-100%, respectively Page 17

20 For voltage outputs: For flags: For counters: 0 Off 1 On 0 Off Non-zero On Counter value The time remaining for the last command is specified in seconds. AUXILIARY STATUS This message is sent by the HAI controller in reply to a REQUEST AUXILIARY STATUS message. The controller reports the status of a group of temperature sensors. The status reported for each temperature sensor includes: the output relay status for Programmable Energy Saver Modules (PESMs), the current temperature reading, and the low and high temperature setpoints. Start character 0x5A Message length (4 * number of temperature sensors) + 1 0x1A Relay status for first temperature sensor Data 2 Current temperature for first temperature sensor Data 3 Low/heat temperature setpoint for first temperature sensor Data 4 High/cool temperature setpoint for first temperature sensor Data 5 Relay status for second temperature sensor Data 6 Current temperature for second temperature sensor Data 7 Low/heat temperature setpoint for second temperature sensor Data 8 High/cool temperature setpoint for second temperature sensor... Data n-3 Relay status for last temperature sensor Data n-2 Current temperature for last temperature sensor Data n-1 Low/heat temperature setpoint for last temperature sensor Data n High/cool temperature setpoint for last temperature sensor The relay status is non-zero if the relay is energized. The temperatures are reported in the Omni temperature format (see Appendix B). Page 18

21 THERMOSTAT STATUS This message is sent by the HAI controller in reply to a REQUEST THERMOSTAT STATUS message. The controller reports the status of a group of thermostats. The status reported for each thermostat includes whether the thermostat is communicating with the controller, whether a freeze condition has been detected by the thermostat, the current temperature, the heat and cool setpoints, the system mode, the fan mode, and whether the thermostat has been placed in hold mode. Start character 0x5A Message length (7 * number of thermostats) + 1 0x1F Status byte for first thermostat Data 2 Current temperature for first thermostat Data 3 Heat setpoint for first thermostat Data 4 Cool setpoint for first thermostat Data 5 System mode for first thermostat Data 6 Fan mode for first thermostat Data 7 Hold status for first thermostat Data 8 Status byte for second thermostat Data 9 Current temperature for second thermostat 0 Heat setpoint for second thermostat 1 Cool setpoint for second thermostat 2 System mode for second thermostat 3 Fan mode for second thermostat 4 Hold status for second thermostat... Data n-6 Status byte for last thermostat Data n-5 Current temperature for last thermostat Data n-4 Heat setpoint for last thermostat Data n-3 Cool setpoint for last thermostat Data n-2 System mode for last thermostat Data n-1 Fan mode for last thermostat Data n Hold status for last thermostat The bits in the thermostat status byte are shown below. The corresponding bit is set if the condition is true. Bit 0 Bit 1 Communications failure Freeze alarm The temperatures are reported in the Omni temperature format (see Appendix B). The system mode is as follows: 0 Off 1 Heat 2 Cool 3 Auto 4 Emergency heat Page 19

22 The fan mode is as follows: 0 Auto 1 On The hold status is non-zero if the thermostat is in hold mode. MESSAGE STATUS This message is sent by the HAI controller in reply to a REQUEST MESSAGE STATUS message. The controller reports the status of displayed text messages. The status reported for each message includes which messages are currently being displayed and what displayed messages have not been acknowledged. For OmniPro II, the status reported also indicates if there is a memo message that has not yet been played. The status of each text message is indicated by two bits. The low order bit is set if the message is currently being displayed on the system console. The high order bit is set if the message has not been acknowledged. The statuses for four messages are packed into one Omni-Link message byte. The status of the lower numbered message is packed into the two high order bits, and the status for the higher numbered messages are packed into the lower order bits. Four data bytes are used to report the status of the 16 messages in an OmniLT. Start character 0x5A Message length 0x06 0x25 0x00 Data 2 status of messages 1-4 Data 3 status of messages 5-8 Data 4 status of messages 9-12 Data 5 status of messages Sixteen data bytes are used to report the status of the 64 text messages in an Omni II system. Start character 0x5A Message length 0x12 0x25 0x00 Data 2 status of messages 1-4 Data 3 status of messages 5-8 Data 4 status of messages status of message status of messages Page 20

23 Thirty-two data bytes are used to report the status of the 128 text messages in an OmniPro and OmniPro II system. Start character 0x5A Message length 0x22 0x25 0x00 (for OmniPro II, bit 0 is set if memo message not yet played) Data 2 status of messages 1-4 Data 3 status of messages 5-8 Data 4 status of messages 9-12 Data 32 status of message Data 33 status of messages SYSTEM EVENT MESSAGES HAI controllers generate system events upon the occurrence of various changes in the controller (see Appendix C). These messages allow the external device to monitor changes in the HAI controller and to react to these changes. By periodically polling for system events the external device can quickly detect and operate on changes in the HAI controller. The REQUEST SYSTEM EVENTS message requests the HAI controller to send a list of system events that have occurred since the controller last reported system events. The controller responds with a SYSTEM EVENTS message that reports each of the system events in the order of occurrence. REQUEST SYSTEM EVENTS Start character Message length Data Expected reply 0x5A 0x01 0x22 none 0x81 0x89 SYSTEM EVENTS SYSTEM EVENTS Start character 0x5A Message length (2 * number of system events) + 1 0x23 High byte of oldest system event Data 2 Low byte of oldest system event Data 3 High byte of next oldest system event Data 4 Low byte of next oldest system event... Data n-1 High byte of most recent event Data n Low byte of most recent event Page 21

24 COMMAND MESSAGE The COMMAND message is used to send an immediate control command to the HAI controller. Commands are provided to control lights, appliances, temperatures, security, and messaging. Each command follows the same format: a single byte command, followed by a single byte parameter, and then a two byte secondary parameter. The command message is formatted as follows: Start character 0x5A Message length 0x05 0x0F Command Data 2 Parameter 1 Data 3 High byte of parameter 2 Data 4 Low byte of parameter 2 Expected reply ACKNOWLEDGE Each of the commands is shown: Command Parameter 1 Parameter 2 Description P1 P n unit P2 off n unit P2 off for P1 seconds n unit P2 off for P1-100 minutes n unit P2 off for P1-200 hours n unit P2 on n unit P2 on for P1 seconds n unit P2 on for P1-100 minutes n unit P2 on for P1-200 hours 2 0-n area P2 all off (0=all areas) 3 0-n area P2 all on (0=all areas) n unit P2 lighting level to P1 percent 10 1-n decrement counter P n increment counter P n set counter P2 to P1 Note: For ALC extended ramp commands, the unit is stored in the low 9 bits of P2. The level to ramp to (0-100%) is stored in the high 7 bits of P2. The rate specifies the full excursion (0% to 100% or 100% to 0%) ramp rate. Smaller excursions will reach the desired level in less time n unit Lo9(P2) ramp to Hi7(P2) at P1 seconds n unit Lo9(P2) ramp to Hi7(P2) at P1-100 minutes n unit Lo9(P2) ramp to Hi7(P2) at P1-200 hours n Lightolier Compose unit P2 off n Lightolier Compose unit P2 on n Lightolier Compose unit P2 scene A-L, respectively Page 22

25 15 1-n send request status message to UPB unit P2 16+s 0 1-n unit P2 dim s steps (s=1-9) 16+s n unit P2 dim s steps (s=1-9) for P1 seconds 16+s n unit P2 dim s steps (s=1-9) for P1-100 minutes 16+s n unit P2 dim s steps (s=1-9) for P1-200 hours 32+s 0 1-n unit P2 brighten s steps (s=1-9) 32+s n unit P2 brighten s steps (s=1-9) for P1 sec 32+s n unit P2 brighten s steps (s=1-9) for P1-100 minutes 32+s n unit P2 brighten s steps (s=1-9) for P1-200 hours 28 1-n UPB link P2 off (deactivate) 29 1-n UPB link P2 on (activate) 30 1-n UPB link P2 set (store preset) n UPB unit P2 LED P1 off n UPB unit P2 LED P1 on 46 1-n RadioRA Phantom Button off 47 1-n RadioRA Phantom Button on 60 1-n scene P2 off (Leviton Scene off command) 61 1-n scene P2 on (Leviton Scene on command) 62 1-n scene P2 set (Leviton Scene set command) For security commands, the code specified must be the user code number rather than the actual four digit security code. That is, send a 0x05 as the code if user code 5 is being used. 48+m 1-n 0-n arm area P2 in mode m with code P1 P2 = 0 means all areas m = security mode: 0 = disarm 1 = day mode 2 = night mode 3 = away mode 4 = vacation mode 5 = day instant mode 6 = night delayed mode 4 1-n 1-n bypass zone P2 with code P1 5 1-n 1-n restore zone P2 with code P1 6 1-n 0-n restore all area P2 zones with code P1 P2 = 0 means all areas/zones The execute macro button command can be used to activate the user operable macro buttons as well as system event macros (see Appendix C). 7 1-n execute macro button P set energy cost to P1 0 = low 1 = mid 2 = high 3 = critical Page 23

26 n energy saver P2 off n energy saver P2 off for P1 seconds n energy saver P2 off for P1-100 minutes n energy saver P2 off for P1-200 hours n energy saver P2 on n energy saver P2 on for P1 seconds n energy saver P2 on for P1-100 minutes n energy saver P2 on for P1-200 hours For commands 66-70, P2 may be set to zero to indicate "all thermostats" in those controllers that support this capability. For the following two commands, temperatures are stored in the Omni temperature format (see Appendix B) where 0 = -40 degc and 255 = 87.5 degc. Thus, corresponds to 0 to 122 degf or -18 to 50 degc n set temp zone P2 low/heat setpoint to P n set temp zone P2 high/cool setpoint to P n set thermostat P2 system mode to P1 0 = off 1 = heat 2 = cool 3 = auto n set thermostat P2 fan mode to P1 0 = auto 1 = on 70 0/255 0-n set thermostat P2 hold mode to P1 0 = off 255 = hold 80 1-n show message P n log message P n 0-n clear message P2 (0=all) if clear all messages, P1 = area (0=all) 83 1-n say message P n 1-n phone number P1 and say message P n 1-n send message P2 out serial port P1 Page 24

27 NAME MESSAGES Display names for zones, units, buttons, codes, areas, thermostats, and messages may be uploaded from and downloaded to the HAI controller through the Omni-Link protocol. Names for all items must be transferred as part of the same upload/download sequence. It is not possible to upload/download the name of a single item without uploading/downloading the names of all items. To upload names from the HAI controller, first send an UPLOAD NAMES message to the HAI controller. The controller will then send a series of NAME DATA messages, followed by a single END OF DATA message. Each NAME DATA message contains the name of a single item. NAME DATA messages are only sent for those items that have a name entered for them. The external device must acknowledge receipt of each NAME DATA message by sending an ACKNOWLEDGE message after each NAME DATA message is received. This informs the HAI controller that the NAME DATA message was received correctly and that the controller may send the next NAME DATA message. If for some reason the NAME DATA message is not received, the external device should send a NEGATIVE ACKNOWLEDGE message to the controller. This instructs the controller to resend the NAME DATA message that was missed. Once all names have been sent, the controller will send an END OF DATA message rather than a NAME DATA message, indicating the end of the name data transfer. If no names have been entered in the controller, the controller will respond with an END OF DATA message rather than a NAME DATA message in reply to the UPLOAD NAMES message. To download names to the HAI controller, first send a DOWNLOAD NAMES message to the HAI controller. This instructs the controller to clear the names of all items and to enter the download names sequence. The controller will reply with an ACKNOWLEDGE message. The external device should then send a series of NAME DATA messages, followed by a single END OF DATA message. Each NAME DATA message contains the name of a single item. NAME DATA messages should only be sent for those items that have a name entered for them. The controller will acknowledge receipt of each NAME DATA message by send an ACKNOWLEDGE message after each NAME DATA message is received. This informs the external device that the NAME DATA message was received correctly and that the external device may send the next NAME DATA message. If the ACKNOWLEDGE message is not received from the controller, the external device should resend the NAME DATA message that was missed. Once all names have been sent, the external device should send an END OF DATA message rather than a NAME DATA message, indicating the end of the name data transfer. The HAI controller will send an ACKNOWLEDGE message in reply to the END OF DATA message. UPLOAD NAMES Start character Message length Data 0x5A 0x01 0x0C none 0x01 0x95 DOWNLOAD NAMES Start character Message length Data 0x5A 0x01 0x0A none 0x81 0x97 Page 25

28 END OF DATA Start character Message length Data 0x5A 0x01 0x03 none 0x41 0x91 NAME DATA For item numbers less than 256, the item number is sent as a single byte: Start character 0x5A Message length (maximum name length, exclusive of terminating zero) + 4 0x0B item type Data 2 item number Data 3 first byte of name... Data n last byte of name For item numbers 256 or greater, the item number is sent as two bytes: Start character 0x5A Message length (maximum name length, exclusive of terminating zero) + 5 0x0B item type Data 2 item number (MSB) Data 3 item number (LSB) Data 4 first byte of name... Data n last byte of name The NAME DATA message specifies the name for a single item. Each name consists of one or more printable ASCII characters, followed by a terminating zero. Zone and message names can be up to 15 characters long, exclusive of the terminating zero. All other names may be up to 12 characters long. Names are always transferred with a fixed number of data bytes for each name type. Thus, a zone name will always be sent as 16 bytes, no matter how long the name really is. The terminating zero indicates the actual end of the name. Data bytes following the terminating zero may be filled with any value. The item type and item number specifies what is being named. The item type identifies whether the name is for a zone, unit, button, code, area, thermostat, or message. The item number identifies the specific zone, unit, button, code, area, thermostat, or message. Page 26

29 Listed below are the item type, maximum name length, and maximum number of each type of name: NAME TYPE LENGTH NUMBER NUMBER NUMBER NUMBER NUMBER (OmniLT) (Omni) (Omni II) (OmniPro) (OmniPro II) Zone Unit Button Code Area Thermostat Message EVENT LOG MESSAGES The HAI controller maintains an event log that records a time stamped listing of significant controller events, such as when the security system is armed/disarmed, alarm activations, and trouble conditions. The event log can store a fixed number of events. OmniLT systems can store 50 events in the event log. Omni systems can store 100 events in the event log. Omni II, OmniPro, and OmniPro II systems can store 250 events in the event log. Once the event log is full, logging a new event will cause the oldest event to be lost. The event log may be uploaded from the HAI controller through the Omni-Link protocol. To upload the event log, first send an UPLOAD EVENT LOG message to the HAI controller. The controller will then send a series of EVENT LOG DATA messages followed by a single END OF DATA message. Each EVENT LOG DATA message contains the data for a single event. The most recent event is sent first. The external device must acknowledge receipt of each EVENT LOG DATA message by sending an ACKNOWLEDGE message after each EVENT LOG DATA message is received. This informs the HAI controller that the EVENT LOG DATA message was received correctly and that the controller may send the next EVENT LOG DATA message. If for some reason the EVENT LOG DATA message is not received, the external device should send a NEGATIVE ACKNOWLEDGE message to the controller. This instructs the controller to resend the EVENT LOG DATA message that was missed. Once the complete event log has been sent, the controller will send an END OF DATA message rather than a EVENT LOG DATA message, indicating the end of the event log transfer. If no events have been logged yet, the controller will respond with an END OF DATA message rather than an EVENT LOG DATA message in reply to the UPLOAD EVENT LOG message. UPLOAD EVENT LOG Start character Message length Data 0x5A 0x01 0x0D none 0xC0 0x55 Page 27

30 EVENT LOG DATA Start character 0x5A Message length 0x0B 0x0E event number (1-n, with 1 being most recent) Data 2 time/date valid Data 3 month (1-12) Data 4 day (1-31) Data 5 hour (0-23) Data 6 minute (0-59) Data 7 event type Data 8 parameter 1 Data 9 high byte of parameter 2 0 low byte of parameter 2 The event number is a simple index that is incremented by 1 for each event log data message. Event 1 is the most recent event. The highest numbered event would be the oldest event. The month, day, hour, and minute specify the time that the event occurred. The time/date valid flag is zero if the controller time was not set when the event occurred. In this case, the month, day, hour, and minute fields do not contain valid data and should not be used. The time/date valid flag is non-zero when the time has been properly set in the controller. The event, parameter 1, and parameter 2 identify the specific event that has occurred. The possible events are shown in the table below. When a security code is specified, the value is the user code number rather than the actual four-digit security code. In addition to the user codes, the following security codes can be reported: 251 Duress code 252 Keyswitch 253 Quick arm 254 PC Access 255 Programmed Page 28

31 EVENT LOG EVENT TYPES Event Type Parameter 1 Parameter 2 P1 P2 Description 4 1-n 1-n zone P2 bypassed with code P1 5 1-n 1-n zone P2 restored with code P1 6 1-n 0-n all area P2 zones restored with code P1 P2 = 0 means all areas/zones 48+m 1-n 0-n area P2 armed in mode m with code P1 P2 = 0 means all areas m = security mode: 0 = disarm 1 = day mode 2 = night mode 3 = away mode 4 = vacation mode 5 = day instant mode 6 = night delayed mode n zone P2 tripped n zone P2 trouble n remote phone access with code P1 131 remote phone lockout n zone P2 auto bypassed n zone P2 trouble cleared n PC access with code P n 1-n alarm P1 activated in area P2 1 = burglary 2 = fire 3 = gas 4 = auxiliary 5 = freeze 6 = water 7 = duress 8 = temperature n 1-n alarm P1 reset in area P2 1 = burglary 2 = fire 3 = gas 4 = auxiliary 5 = freeze 6 = water 7 = duress 8 = temperature 137 system reset n message P2 logged Page 29

32 VALIDATE SECURITY CODE MESSAGES These messages instruct the controller to confirm that the specified four-digit security code is valid in the specified area. The code is only valid if it matches a four-digit user code in the area, and that code is currently time-enabled. The controller will return the user code number and authority level for the code. The controller will also check to see if the duress code was specified. If so, it will return the duress code number (251) as the user code number and set the authority level to user. REQUEST SECURITY CODE VALIDATION Start character 0x5A Message length 0x06 0x26 area number (1-8) Data 2 first digit of code Data 3 second digit of code Data 4 third digit of code Data 5 fourth digit of code Each of the digits of the security code must be sent as the numeric value of the digit, 0x00 through 0x09. SECURITY CODE VALIDATION Start character Message length Data 2 0x5A 0x03 0x27 user code number (1-99, 251 for duress, 0 if invalid) authority level The authority level is as follows: 0 Invalid code 1 Master 2 Manager 3 User Page 30

33 APPENDIX A - CRC-16 ERROR DETECTION ROUTINES This first routine is written in Turbo Pascal. First initialize CRC to 0. Then, starting with the message length byte, call Update_CRC for each byte of the message passing the message byte in Data. The low byte of CRC will contain the low byte of the CRC-16 remainder and should be sent first. The high byte of CRC will contain the high byte of the CRC-16 remainder and should be sent last. var CRC: Word; procedure Update_CRC(Data: Byte); const Poly = $A001; {CRC-16 polynomial} var I: Integer; Flag: Boolean; begin CRC := CRC xor Data; for I := 1 to 8 do begin Flag := (CRC and 1) <> 0; CRC := CRC shr 1; if Flag then CRC := CRC xor Poly; end; end {Update_CRC}; This next routine is written in Motorola MC68HC11 assembly language. First initialize CRC+0 and CRC+1 to 0. Then, starting with the message length byte, call UPDCRC for each byte of the message with the B accumulator containing the message byte. CRC+1 will contain the low byte of the CRC-16 remainder and should be sent first. CRC+0 will contain the high byte of the CRC-16 remainder and should be sent last. POLY EQU $A001 CRC-16 polynomial UPDCRC 10$ 20$ PSHB save registers PSHA EORB CRC+1 add in new byte LDAA #8 get shift count STAA CRC+1 use low byte of CRC for counter LDAA CRC+0 get high byte of CRC LSRA shift CRC RORB BCC 20$ branch if we didn't shift out a 1 EORA #>POLY add in CRC polynomial EORB #<POLY DEC CRC+1 count the shift BNE 10$ branch back if more to do STD CRC save updated CRC PULA restore registers PULB RTS Page 31