Message Formatting
   

Commands can be sent in either ASCII (text) or raw format.

In ASCII format, the commands are split into parameters. In raw format the commands are split into binary words which contain the parameters.

Each command contains:

 

Note:

  • When sending raw commands, certain command words have been reserved for future use. These should always be given the value of 0 when creating commands.

  • When you send a command, if you have entered an invalid parameter or it has been sent to a device, router or cluster that does not exist, then you will receive an error message describing what is wrong with the command. See Error / Diagnostic Messages.

ASCII Format

The ASCII format requires that certain rules concerning special characters, parameter identifiers, and delimiters be adhered to. These rules are as follows:

  1. The ASCII string must begin with the command character ‘>’ and end with the terminator character ‘#’.

  2. Replies to queries begin with the character ‘?’.

    The data concerning a query’s response is separated from the query string by the character ‘=’.

    The whole query response string is terminated with one of the following characters:

    For example, a response that contains more data than the maximum message size would be split into two responses. The first partial response would be terminated by ‘$’, and the second partial response would be terminated by ‘#’.

  3. Error/Diagnostic messages begin with the character ‘!’ and, again, end in ‘#’.

  4. Unless they are optional, all of the parameters required for the command must be included. Otherwise, the message is rejected and discarded.

  5. The ASCII parameters are not required to be ordered.

  6. The parameter identifiers are to be included as shown in the following table, i.e. all alphabetic identifiers should be in upper case.

 

Description

Character

Optional

Hex

Character Type

Command

>

No

0x3E

Message Type

Internal Command

<

No

0x3C

Message Type

Reply

?

No

0x3F

Message Type

Error / Diagnostic

!

No

0x21

Message Type

 

Terminator

#

No

0x23

Special

Partial reply terminator

$

No

0x24

Special

Answer

=

No

0x3D

Special

 

Delimiter

,

No

0x2C

Delimiter

Parameter ID Delimiter

:

No

0x3A

Delimiter

Address Delimiter

.

No

0x2E

Delimiter

 

Sequence Number

Q

For internal commands only

0x51

Parameter ID

HelvarNet Version

V

Version 1 only (assumes version 1)

0x56

Parameter ID

Command

C

No

0x43

Parameter ID

Acknowledgment

A

Yes (assumes a value of 0)

0x41

Parameter ID

Address

@

No

0x40

Parameter ID

Group

G

Yes (assumes a value of 1)

0x47

Parameter ID

Scene

S

Yes (assumes a value of 1)

0x53

Parameter ID

Block

B

Yes (assumes a value of 1)

0x42

Parameter ID

Fade Time

F

Yes (assumes 700ms)

0x46

Parameter ID

Level

L

No

0x4C

Parameter ID

Proportion

P

No

0x50

Parameter ID

Display Screen

D

No

0x44

Parameter ID

Time

T

No

0x54

Parameter ID

Latitude

N

No

0x4E

Parameter ID

Longitude

E

No

0x45

Parameter ID

Time Zone Difference

Z

No

0x5A

Parameter ID

Daylight Saving Time (DST)

Y

No

0x59

Parameter ID

Constant Light Scene

K

Yes (assumes false)

0x4B

Parameter ID

Force Store Scene - Intensity

O

Yes (assumes false)

0x4F

Parameter ID

Force Store Scene - Colour

H

Yes (assumes false)

0x48

Parameter ID

Colour X

CX

Yes (assumes false)

0x4358

Parameter ID

Colour Y

CY

Yes (assumes false)

0x48

Parameter ID

Mireds

M

Yes (assumes false)

0x4D

Parameter ID

Colour Ignore

CI

Yes (assumes false)

0x4349

Parameter ID

Device Category

DC

Yes (assumes false)

0x4443

Parameter ID

 

For example, in the command Recall Group 1234, Block 5, Scene 6, Fade Time 32 s, the string is sent as follows, including the delimiters and the start character ‘>’ and stop character ‘#’:

>V:1,C:11,G:1234,B:5,S:6,F:3200#

Note:

This ASCII representation for the above scene recall takes one byte per ASCII character, resulting in 26 bytes being transmitted.

 Raw Format

  1. Command data is transmitted using the network byte order (big-endian).

  2. All commands must be ten Words in length (each Word being a 32 bit / 4 Byte value). Words five & six are reserved for future expansion to the addressing capabilities, and Words nine and ten are reserved to accommodate any changes or future requirements in the parameters.

Note:

  • All ten words must be sent, including all reserved words.

For example, the command (Recall Group 1234, Block 5, Scene 6, Fade Time 32 s) is transmitted as follows (note that the trailing zeros are included and mandatory):

0x0001000B  0x000004D2  0x00000000  0x00050006  0x00000000  0x00000000  0x00000000  0x00000C80  0x00000000  0x00000000

Note:

  • In the first 32 bit word, the message type (see below), version number (1) and command number must be included.

Raw Message Types, Versions and Command Numbers

The raw message types are as follows:

0 = Command

1 = Reply

2 = Error / Diagnostic

 

The message type number is the included as the first byte of the 32 bit Word of the command. E.g. If you send a Query Clusters command, the first Word of the reply will be:

0x01010065

(1 denoting that the message is a reply)

 

31.................24

23.....................16

15...................8

7....................0

Message Type [31:24]

Ack [23]

Version [22:16]

Command Number [15:0]

Byte 3

Byte 2

Byte 1

Byte 0

 

Data Word Format (big-endian)

WORD - 32 bits / 4 bytes

Byte 3 (MSB)

Byte 2

Byte 1

Byte 0

31.................24

23.....................16

15...................8

7....................0

 

 Related Topics