Knowledge Base - Hardware

amBIENT XC RS232 Control Command Specification

Download PDF version of this document

  1. Goal

The RS232 protocol allows:

  • Override the schedule with a certain mode
  • Return to the scheduled mode

  1. COM port properties

To communicate over RS232 with the amBIENT XC, the following COM port properties should be set:

  • Bits per second: 9600
  • Data bits: 8
  • Parity: None
  • Stop bits: 1

  1. Initialisation of RS232 communication

To initialize the RS232 communication, the first packet that should be sent to the amBIENTXC should be the initialise packet (see below), with 10 data bytes, all set to zero. The amBIENTXC will not send a response to this message.

Initialise packet

Description Length Value
Destination 1 byte 0x63 ("c")
Message type 1 byte 0x49 ("I")
Data length 1 byte 0x0A
Data bytes 1 - 10 10 bytes 0x00 (10 times)

  1. Determine the protocol version

The packet below allows an application to determine the RS232 protocol version of the product:

 

GetDeviceInfo packet

Description Length Value
Destination 1 byte 0x47 ("G")
Message type 1 byte 0x47 ("G")
Data length 1 byte 0x00

 

Response

Description Length Value
Destination 1 byte 0x52 ("R")
Message type 1 byte 0x47 ("G")
Data length 1 byte 0x01 
Protocol version 1 byte 0x02

  1. Control Protocol

  1. Message format

Description Length
Destination 1 byte
Message type 1 byte
Data length 1 byte
Data 0-58 bytes
CRC 1 byte

The CRC is a byte by byte X-OR or the total packet (header+data).

  1. Destinations

Destination Value
RS232 source (PC/crestron/lutron controller) 0x52 ("R")
amBX network layer - CTRL interface 0x63 ("c")
General 0x47 ("G")

The destinations are clarified in more detail in the picture below. Commands that are sent from the controlling device (e.g. a PC or a touch panel) should use "G" or "c" as destination (which one to use is detailed in the message structures below). Responses, sent from amBIENTXC to the controlling device use "R" as destination.

image

  1. Message types

Message type Value
Reserved 0x58 ("X")
Connect 0x43 ("C")
Disconnect 0x44 ("D")
SetOverride 0x6F ("o")

  1. Connect

Description Length Value
Destination 1 byte 0x63 ("c")
Message type 1 byte 0x43 ("C")
Data length 1 byte 0x01
CRC 1 byte 0x21

 

Response

Description Length Value
Destination 1 byte 0x52 ("R")
Message type 1 byte 0x43 ("C")
Data length 1 byte 0x02
Result 1 byte  
CRC 1 byte  

 

Result

  • OK
  • Error
  • CRC incorrect

Result codes: see section 4.7.

  1. Disconnect

Description Length Value
Destination 1 byte 0x63 ("c")
Message type 1 byte 0x44 ("D")
Data length 1 byte 0x01
CRC 1 byte 0x26

 

Response

Description Length Value
Destination 1 byte 0x52 ("R")
Message type 1 byte 0x44 ("D")
Data length 1 byte 0x02
Result 1 byte  
CRC 1 byte  

Result:

  • OK
  • Error
  • NotConnected
  • CRC incorrect

Result codes: see section 4.7.

  1. SetOverride

Description Length Value
Destination 1 byte 0x63 ("c")
Message type 1 byte 0x6F ("o")
Data length 1 byte 0x07
ModeID 1 byte ModeID
Transition time 4 bytes  
Start conditions 1 byte  
CRC 1 byte For CRC values see Table 1

 

ModeID values: 0x00 - 0x0C (0 to 12).

ModeID=0x00 means "return to the schedule".

Mode 1 to 12 relate to the amBIENT XC on screen modes, as depicted in Figure 1.

Transition time: 0x00000000 (currently not supported)

Start conditions: Boolean. False = 0x00, TRUE = 0x01 (typically TRUE)

If set to false, the start conditions of the mode effects are ignored.

 

image

Figure 1: amBIENT XC modes

 

Response

Description Length Value
Destination 1 byte 0x52 ("R")
Message type 1 byte 0x6F ("o")
Data length 1 byte 0x02
Result 1 byte  
CRC 1 byte  

Result

  • OK
  • Error
  • NotConnected
  • ModeDoesNotExist
  • CRC incorrect

Result codes: see section 5.7.

 

Table 1: CRC values for setOverride

Mode Start condition CRC     Mode Start Condition CRC
0x00 0x00 0x0b     0x07 0x00 0x0c
0x01 0x00 0x0a     0x07 0x01 0x0d
0x01 0x01 0x0b     0x08 0x00 0x03
0x02 0x00 0x09     0x08 0x01 0x02
0x02 0x01 0x08     0x09 0x00 0x02
0x03 0x00 0x08     0x09 0x01 0x03
0x03 0x01 0x09     0x0a 0x00 0x01
0x04 0x00 0x0f     0x0a 0x01 0x00
0x04 0x01 0x0e     0x0b 0x00 0x00
0x05 0x00 0x0e     0x0b 0x01 0x01
0x05 0x01 0x0f     0x0c 0x00 0x07
0x06 0x00 0x0d     0x0c 0x01 0x06
0x06 0x01 0x0c          

 

  1. Result codes

Description Value
OK 0x00
Error 0x01
NotConnected 0x04
ModeDoesNotExist 0x07
CRC incorrect 0x08

  1. amBIENT XC behaviour

After disconnecting, the amBIENT XC can be in different states, dependent on commands that have been called.

amBIENT XC state before connecting Commands amBIENT XC state after connecting
amBIENT XC runs according to the time table
  • Connect
  • Disconnect
 amBIENT XC runs according to the time table
amBIENT XC runs according to the time table
  • Connect
  • Setoverride 0x01 - 0x0C
  • Disconnect
 amBIENT XC runs in override mode (until a (scheduled) reboot happens).
amBIENT XC runs according to the time table
  • Connect
  • Setoverride 0x01 - 0x0C
  • SetOverride 0x00
  • Disconnect
 amBIENT XC runs according to the time table
amBIENT XC is in override mode
  • Connect
  • Disconnect
 amBIENT XC is in override mode
amBIENT XC is in override mode
  • Connect
  • Setoverride 0x01 - 0x0C
  • Disconnect
 amBIENT XC is in override mode
amBIENT XC is in override mode
  • Connect
  • Setoverride 0x01 - 0x0C
  • SetOverride 0x00
  • Disconnect
 amBIENT XC runs according to the time table

Note that after a reboot, the amBIENT XC automatically runs according to the time table. Reboots occur after uploading modes, uploading new firmware, and at the daily reboot time.

  1. Implementation remarks

Note: the current implementation of the amBIENT XC RS232 protocol has minor deviations from the specification of chapter 5:

  • The destination field in the responses can be both "R" and "U".
  • The protocol version can be different than 0x02.

Last Updated on Wednesday, 02 June 2010 11:03 Monday, 10 May 2010 13:35