HA-I02.01
Current development revision
This document describes the CAN higher-level protocol description for use on the home automation bus.
All numerical values are decimal unless explicitly stated otherwise.
Contents
- HA-I02.01
- Message identifiers
- Messages
- Message flow overview
Message identifiers
In general, the "standard" addressing scheme with 11-bit identifiers is used. The first 4 bits (bit 10..7) are used to identify the message type (message type ID, MTID), the last 7 bits (bit 6..0) are used to uniquely identify a device on the bus.
15 |
14 |
13 |
12 |
11 |
10 |
9 |
8 |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
(bus ID) |
MTID |
Device ID |
|||||||||||||
This allows for 15 message types to be transmitted (see below for explanation and assignment) and 128 devices on the bus. Certain device addresses are reserved for future use, so this will lead to 120 uniquely addressable devices on the CAN bus. A multi-bus configuration with routing capabilities is taken into account in this protocol definition.
Message Type Identifiers (MTIDs)
MTID |
Description |
00 |
reserved |
01 |
System management message, high priority |
02 |
reserved |
03 |
reserved |
04 |
reserved |
05 |
Input status sense, digital, pulse |
06 |
Output status command, digital |
07 |
Output status command, value |
08 |
reserved |
09 |
Input status sense, value |
10 |
Input status sense, digital, permanent |
11 |
reserved |
12 |
reserved |
13 |
System management message, low priority |
14 |
reserved |
15 |
invalid |
Blocking MTID 15 from use fulfils the CAN standard's requirement that not all of the first 7 bit may be recessive (logical 1).
Device identifiers
The following device identifiers (DIDs) are reserved for special purposes or future use.
DID |
Description |
000 |
USB/CAN interface HA-B02 |
121 |
Automatic CAN Address Assignment (ACAA) HA-I01 |
122 |
reserved |
123 |
reserved |
124 |
reserved |
125 |
reserved |
126 |
reserved |
127 |
reserved |
Messages
This section will explain the data transmitted in the CAN message datagrams which depends on the message type and thus can be identified by a bus member by first classifying the datagram according to its MTID and then parsing the message payload.
MTID 01, System management message, high priority
to be defined
MTID 05, Input status sense, digital, pulse
This message signals the detection of a pulse on a digital pulse input. The message is generated when an input known to be a digital pulse input is activated. The message is not repeated when the input stays active for any amount of time. After the input goes passive (deactivated) for a duration depending on the input and bus device specification and implementation, it can be triggered again, causing this message to be sent again.
An example might be a pushbutton having been pushed. When the user presses the button, this message is sent. When the user holds down the button after pressing it, no further action is taken. The next message will be sent when the user releases the button and it is pressed again.
Double-click functionality is currently only specified as a concept to be supported by the respective devices, implementation details are yet to be defined.
data length |
data 0 |
data 1 |
2 |
input number |
flags |
Flags can be one of the following:
flag |
description |
00 |
no special flags set |
01 |
double-click detected |
MTID 06, Output status command, digital
This message commands an output device to set one digital output to a certain state.
data length |
data 0 |
data 1 |
2 |
output number |
state |
State can be one of the following:
state |
description |
00 |
output not energized |
01 |
output energized |
06 |
output pulse high |
10 |
output pulse low |
The output pulse commands are executed only when the output is already set to the respective other stable state when the command arrives. For example, when an output is switched off, an output pulse low command will be ignored.
MTID 07, Output status command, value
This message commands an output device to set one multi-value (e.g. analog) output to a certain value.
data length |
data 0 |
data 1 |
2 |
output number |
value |
Value can be 0..255, though not all output devices need to implement the full range of values. See MTID 13, D_RANGE command, for means of determining the available value ranges per output device.
MTID 09, Input status sense, value
This message signals a changed value on a multi-value input device, e.g. an analog or multi-step input.
data length |
data 0 |
data 1 |
2 |
input number |
value |
Value can be 0..255, though not all input devices need to implement the full range of values. See MTID 13, D_RANGE command, for means of determining the available value ranges per input device.
MTID 10, Input status sense, digital, permanent
This message signals a changed state in a latching digital input device, e.g. a classic light switch.
data length |
data 0 |
data 1 |
2 |
input number |
state |
State can be either 0 or 1, representing the two possible states of the input device.
MTID 13, System management message, low priority
This message type can carry several types of low priority bus and system management traffic.
data length |
data 0 |
data N |
variable |
Command |
command-specific |
Total data length is depending on the actually transmitted management message, but always at least one byte of data is included, giving the "command identifier" (CI) that is used to distinguish the different types of management datagrams that can be transferred using this MTID.
CI |
short name |
description |
further data included |
total data length |
000 |
reserved |
reserved |
none |
1 |
001 |
ONBUS |
Device is on the bus, running and active |
none |
1 |
002 |
OFFBUS |
Device is going to (orderly) leave the bus |
none |
1 |
003 |
SLEEPING |
Device is going into a (device-specific) sleep mode |
none |
1 |
004 |
E_COUNTER |
CAN error counters |
RXERR value, TXERR value |
3 |
005 |
E_OFLOW |
Counter of overflow conditions since last reset |
RX0 overflow counter, RX1 overflow counter |
3 |
006 |
E_WARN |
CAN error counter reached the warning level |
1..3: 1=TXERR 2=RXERR 3=both |
2 |
007 |
E_ERRORS |
Counter of error states since last reset |
error-passive counter, error-off counter |
3 |
030 |
S_FAIL |
Input device failure detected, input deactivated |
input number |
2 |
031 |
S_DEGRADED |
Input device failure detected, input operating in degraded mode |
input number |
2 |
032 |
S_OKAY |
Input device is working fine (again) |
input number |
2 |
033 |
S_OFAIL |
Output device failure detected, output deactivated |
output number |
2 |
034 |
S_ODEGRAD |
Output device failure detected, output operating in degraded mode |
output number |
2 |
035 |
S_OOKAY |
Output device is working fine (again) |
output number |
2 |
040 |
D_RANGE |
Signals the supported range for a multi-value input or output |
I/O number, minimum value, maximum value |
4 |
041 |
D_NAMERQ |
Requests a human readable name for a device ID |
device ID, I/O number |
3 |
042 |
D_NAMERP |
Reply to a D_NAMERQ request |
device name, six ASCII chars, left-padded with space characters |
7 |
043 |
D_VERSION |
Currently active firmware revision index |
index |
2 |
044 |
D_DEVTYPE |
Device type ID (DTID) |
DTID |
2 |
045 |
D_IORANGE |
Number of input and output lines on this bus device |
input count, output count |
3 |
060 |
I_WTIME |
Current wall-clock time |
day of week (0=Sunday), day of month, hour (24h format), minute |
8 |
070 |
M_ACAARQ |
ACAA address request |
Device type identifier |
2 |
071 |
M_ACAASG |
ACAA address assignment |
Newly assigned CANID |
2 |
072 |
M_ACAACK |
ACAA check handshake |
none |
1 |
255 |
reserved |
reserved |
none |
1 |
Notes
ONBUS is transmitted by a bus member right after joining the bus. It is afterwards transmitted again automatically by an active bus member at least every 300 seconds, but not more often than once every 60 seconds.
OFFBUS is transmitted when a device is about to shut down and be no longer reachable through the bus without certain activity that cannot be initiated remotely through the bus itself. It is, therefore and due to protocol specification, not transmitted when a device goes into the "passive" or "off" state after a CAN protocol error.
SLEEPING is transmitted before a device is entering a sleep mode where it might consume less energy than in normal mode. To become active, this device might require an ONBUS remote frame request to wake it up. After waking up, the device is supposed to send an ONBUS message.
E_COUNTER is only transmitted on request by another bus device, usually the HA-bus control station.
E_OFLOW is only transmitted on request by another bus device, usually the HA-bus control station.
E_ERRORS is transmitted by a device after it has cleared one of the reported CAN error states. It can also be requested by another bus device, usually the HA-bus control station.
D_RANGE values are, as all data transmitted in single bytes, ranging 0..255.
D_DEVTYPE contains a device type identification number which is explained elsewhere.
I_WTIME data field lengths: weekday is 1 Byte, day, hour, minute are 2 Bytes each.
I_WTIME is transmitted by time sources (such as the control computer) about every 20 seconds.
The control station is allowed to issue a remote transmit request for MTID 13 directed to any bus device address. The bus device, if present, is expected to respond to this by sending one or more MTID 13 datagrams. The addressed device is required to respond with a CI 001 ONBUS message shortly (within 300 ms) after receipt of the RTR. The actual number of MTID 13 commands transmitted in response as well as the CIs additionally transmitted is device-specific, and documented in the respective part description.
Message flow overview
This section is not part of the protocol specification but serves informational purposes only.
THIS DATA IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DATA, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
All product and brand names mentioned on there pages and in the source code are registered names and/or trademarks of the respective owner and are mentioned for identification purposes only.
For a full copyright notice, please see this link. For imprint and contact information, please see http://www.thiemo.net/.