ambient XC RS232 Control Command Specification Table of Contents ambient XC RS232 Control Command Specification...1 Goal...2 COM port properties...2 Initialisation of RS232 communication...2 Determine the protocol version...3 Control Protocol...4 Message format...4 Destinations...4 Message types...5 Connect...5 Response...5 Disconnect...6 Response...6 SetOverride...7 Response...8 Result codes...9 Set Saturation...10 Set Brightness...10 Special Command to Change the Palette Colours of the Current Light-Scene...13 ambient XC behaviour...13 Implementation remarks...15 Examples...15 Change the Current Light-Scene...15 Change the Brightness of the Current Light-Scene...16 Change the Palette of the Current Light-Scene...17 1
ambient XC RS232 Control Command Specification Goal The RS232 protocol allows : Override the schedule with a certain mode Return to the scheduled mode 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 XC RS232 Pinout DB 9 Connector on the XC: RX - Pin 3 TX - Pin 2 GND - Pin 5 Initialisation of RS232 communication To initialize the RS232 communication, the first packet that should be sent to the ambient XC should be the initialise packet (see below), with 10 data bytes, all set to zero. The ambient XC will not send a response to this message. Initialise packet Destination 0x63 ( c ) Message type 0x49 ( I ) Data length 0x0A Data bytes 1 10 10 bytes 0x00 (10 times) ambx UK Ltd 2013 2
Determine the protocol version The packet below allows an application to determine the RS232 protocol version of the product: GetDeviceInfo packet Destination 0x47 ( G ) Message type 0x47 ( G ) Data length 0x00 Response Destination 0x52 ( R ) Message type 0x47 ( G ) Data length 0x01 Protocol version 0x02 3
ambient XC RS232 Control Command Specification Control Protocol Message format Description Destination Message type Data length Data CRC Length 0-58 bytes The CRC is a byte by byte X-OR or the total packet (header+data). Destinations Destination RS232 source (PC/crestron/lutron controller) ambx network layer CTRL interface General Value 0x52 ( R ) 0x63 ( c ) 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. RS232 source ambientxc R G c G or c R ambx UK Ltd 2013 4
Message types Message type Reserved Connect Disconnect SetOverride Value 0x58 ( X ) 0x43 ( C ) 0x44 ( D ) 0x6F ( o ) Connect Destination 0x63 ( c ) Message type 0x43 ( C ) Data length 0x01 CRC 0x21 Response Destination 0x52 ( R ) Message type 0x43 ( C ) Data length 0x02 Result CRC Result OK Error CRC incorrect Result codes: see page 9. 5
ambient XC RS232 Control Command Specification Disconnect Destination 0x63 ( c ) Message type 0x44 ( D ) Data length 0x01 CRC 0x26 Response Destination 0x52 ( R ) Message type 0x44 ( D ) Data length 0x02 Result CRC Result: OK Error NotConnected CRC incorrect Result codes: see section. ambx UK Ltd 2013 6
SetOverride Destination 0x63 ( c ) Message type 0x6F ( o ) Data length 0x07 ModeID ModeID Transition time Start conditions 4 bytes CRC 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. Figure 1: ambient XC modes 7
ambient XC RS232 Control Command Specification Response Destination 0x52 ( R ) Message type 0x6F ( o ) Data length 0x02 Result CRC Result OK Error NotConnected ModeDoesNotExist CRC incorrect Result codes: see page 9. ambx UK Ltd 2013 8
Mode Start CRC Mode Start CRC condition Condition 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 Table 1: CRC values for setoverride Result codes Description OK Error NotConnected ModeDoesNotExist CRC incorrect Value 0x00 0x01 0x04 0x07 0x08 9
ambient XC RS232 Control Command Specification Set Saturation Command Response 63 63 03 01 <value> (02 XOR <value>) 52 63 02 <returncode> (33 XOR <returncode>) <value> has the range 0 100. 50 is the normal value. Any values above that being over saturated (a tend towards a more primary colour). Where <aa> XOR <bb> is the bitwise exclusive OR of <aa> with <bb> as shown in the tables below: Set Brightness Command Response 63 63 03 00 <value> (03 XOR <value>) 52 63 02 <returncode> (33 XOR <returncode>) <value> has the range 0 100. 50 is the normal value. Any values above that being over-brightness (with a possible loss of colour definition). Where <aa> XOR <bb> is the bitwise exclusive OR of <aa> with <bb> as shown in the tables below: ambx UK Ltd 2013 10
<value> (02 XOR <value>) <value> (02 XOR <value>) <value> (02 XOR <value>) 0 2 21 23 42 40 1 3 22 20 43 41 2 0 23 21 44 46 3 1 24 26 45 47 4 6 25 27 46 44 5 7 26 24 47 45 6 4 27 25 48 4A 7 5 28 2A 49 4B 8 0A 29 2B 4A 48 9 0B 2A 28 4B 49 0A 8 2B 29 4C 4E 0B 9 2C 2E 4D 4F 0C 0E 2D 2F 4E 4C 0D 0F 2E 2C 4F 4D 0E 0C 2F 2D 50 52 0F 0D 30 32 51 53 10 12 31 33 52 50 11 13 32 30 53 51 12 10 33 31 54 56 13 11 34 36 55 57 14 16 35 37 56 54 15 17 36 34 57 55 16 14 37 35 58 5A 17 15 38 3A 59 5B 18 1A 39 3B 5A 58 19 1B 3A 38 5B 59 1A 18 3B 39 5C 5E 1B 19 3C 3E 5D 5F 1C 1E 3D 3F 5E 5C 1D 1F 3E 3C 5F 5D 1E 1C 3F 3D 60 62 1F 1D 40 42 61 63 20 22 41 43 62 60 63 61 64 66 11
ambient XC RS232 Control Command Specification <value> (03 XOR <value>) <value> (03 XOR <value>) <value> (03 XOR <value>) 0 3 21 22 42 41 1 2 22 21 43 40 2 1 23 20 44 47 3 0 24 27 45 46 4 7 25 26 46 45 5 6 26 25 47 44 6 5 27 24 48 4B 7 4 28 2B 49 4A 8 0B 29 2A 4A 49 9 0A 2A 29 4B 48 0A 9 2B 28 4C 4F 0B 8 2C 2F 4D 4E 0C 0F 2D 2E 4E 4D 0D 0E 2E 2D 4F 4C 0E 0D 2F 2C 50 53 0F 0C 30 33 51 52 10 13 31 32 52 51 11 12 32 31 53 50 12 11 33 30 54 57 13 10 34 37 55 56 14 17 35 36 56 55 15 16 36 35 57 54 16 15 37 34 58 5B 17 14 38 3B 59 5A 18 1B 39 3A 5A 59 19 1A 3A 39 5B 58 1A 19 3B 38 5C 5F 1B 18 3C 3F 5D 5E 1C 1F 3D 3E 5E 5D 1D 1E 3E 3D 5F 5C 1E 1D 3F 3C 60 63 1F 1C 40 43 61 62 20 23 41 42 62 61 63 60 64 67 (33 XOR <returncode>) <returncode> 33 0 32 1 37 4 34 7 3B 8 ambx UK Ltd 2013 12
Special Command to Change the Palette Colours of the Current Light-Scene A special command has been added to allow the five palette entries for the current Light-Scene to be changed. This command has its own protocol as follows: Command Command bytes (in hex) Response bytes (in hex) Change Palette Colour 00 00 04 00 A5 00 5A 00 09 00 21 00 72 75 6e 2f 65 65 67 00 00 00 00 00 00 00 00 00 00 00 02 00 00 00 00 00 Offset 00 00 00 03 00 R G B 01 00 01 00 00 00 00 01 00 00 09 00 01 00 00 01 00 01 00 00 Where Offset is the offset into the palette entries, the first palette entry is 00 and each entry is 3 bytes so the second palette entry is offset 03 etc see below: Offset Entry 00 Palette 1 03 Palette 2 06 Palette 3 09 Palette 4 0c Palette 5 R, G and B are byte values for red green and blue respectively. ambient XC behaviour After disconnecting, the ambient XC can be in different states, dependent on commands that have been called. 13
ambient XC RS232 Control Command Specification XC state before connecting XC runs according to the timetable XC runs according to the timetable XC runs according to the timetable XC is in override mode XC is in override mode XC is in override mode Commands Connect Disconnect Connect Setoverride 0x01 0x0C Disconnect Connect Setoverride 0x01 0x0C SetOverride 0x00 Disconnect Connect Disconnect Connect Setoverride 0x01 0x0C Disconnect Connect Setoverride 0x01 0x0C SetOverride 0x00 Disconnect XC state after connecting XC runs according to the timetable XC runs in override mode (until a (scheduled) reboot happens). XC runs according to the timetable XC is in override mode XC is in override mode XC runs according to the timetable 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. ambx UK Ltd 2013 14
Implementation remarks Note: the current implementation of the ambient XC RS232 protocol has minor deviations from the specification of Determine the protocol version, above The destination field in the responses can be both R and U. The protocol version can be different than 0x02. Examples In the examples below the command sent to the XC is in the Command bytes column. Each byte is represented by two hex digits; ten decimal being shown as 0a for example. These bytes are sent (as binary data not ascii) via the RS232 link to the XC. The XC will respond as shown in the Response bytes column across the same link. Change the Current Light-Scene Suppose it is required to change the current Light-Scene to number 5, then to Light-Scene 12. First a connection must be established: Command Command bytes (in hex) Response bytes (in hex) Connect 63 43 01 21 52 43 02 00 13 Now the Light-Scene can be selected. Select Light-Scene 63 6f 07 05 00 00 00 00 01 0f 52 6f 02 00 3f The Light-Scene in slot 5 will now be controlling the lights. To change to Light-Scene to number 12 (0c hex) the following command can be issued (note there is no need to repeat the connect command unless a disconnect command has already been issued). 15
ambient XC RS232 Control Command Specification Select Light-Scene 63 6f 07 0c 00 00 00 00 01 06 52 6f 02 00 3f The Light-Scene in slot 12 will now be controlling the lights. To return control to the front-panel user a disconnect command is issued: Disconnect 63 44 01 26 52 44 02 00 14 Change the Brightness of the Current Light-Scene Suppose it is required to change the brightness of the current Light-Scene to 63 (3f hex). If not already connected a connection must be established: Command Command bytes (in hex) Response bytes (in hex) Connect 63 43 01 21 52 43 02 00 13 Now the brightness can be changed. Change Brightness 63 63 03 00 3f 3c 55 43 02 00 14 To find the CRC value (3c in this example) the CRC table is consulted and the value corresponding to 3f in the <value> column is found in the (03 XOR <value>) column (3f in this case). ambx UK Ltd 2013 16
Change the Palette of the Current Light-Scene Suppose we want to change the colour of the second palette entry (offset 03) to RGB 27, 126, 0 ( 1b 7e 00 ). The following command would be sent: Command Command bytes (in hex) Response bytes (in hex) Change Palette Colour 00 00 04 00 A5 00 5A 00 09 00 21 00 72 75 6e 2f 65 65 67 00 00 00 00 00 00 00 00 00 00 00 02 00 00 00 00 00 03 00 00 00 03 00 1b 7e 00 01 00 01 00 00 00 00 01 00 00 09 00 01 00 00 01 00 01 00 00 Note that if the XC is currently connected using the main protocol you do not need to disconnect before connecting with the palette change protocol. 04/29/13 01:54:55 PM 17