Link-2-PC-Serial (RS232) Command Reference Guide

This document assumes that one is communicating to a GR 2400 bus via a LINK to PC-RS 232/USB card. The method of controlling a GR 2404 –iDim card is described first followed by the data on switching and polling status of a relay panel.

Nomenclature:

In this document hexadecimal values are represented as in ANSI C programming due to its wide usage in embedded environments.

In this format each hexadecimal value is preceded by ‘0x‘.

(E.g.: decimal value 10 would be represented as 0x0a instead of just simply 0a)

WHEN PHYSICALLY SENDING CHARACTERS TO THE Link-To PC Card

ALL ‘0x’ MUST BE OMITTED.

Also note that apostrophes are never sent. They are strictly used as separators in this document.

RS-232 command structure of the Link-To PC:

The link-To PC accepts commands sent as hexadecimal byte values in 2 character ASCII representation. This means that every value sent must be converted into hexadecimal and that hexadecimal number must be sent as 2 ASCII characters. The Link-To PC accepts the hexadecimal values in both lower and uppercase format. Thus the valid characters are: 0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f,A,B,C,D,E,F)

The Link-To PC sends hexadecimal data in lower case format.

All command and data must be in this format no exception.

Each command consists of a series of bytes followed by an enter character. (Character value 0x0d note that this is the enter character itself that is ASCII character number 13 (decimal) which is a single character and NOT the 2 char representation of the value 0x0d)

Other than the previously mentioned this is the only other character recognized by the Link-To PC.

Each command must have a valid checksum byte as the last byte of the command.

This is the last byte sent before the enter character.

The checksum must be calculated for every command properly. Bad checksum will result in the rejection of the command.

Checksum Calculation:

Generate a the sum of each byte in a command using simple addition.

(That is take the all the bytes of a command one by one and add them together)

Take the least significant 8 bits (modulo 8) value of that sum.

As with all the bytes sent to the Link-To PC send this value right after all the other bytes of the command (but before the enter character) in hexadecimal as 2 ASCII characters.

Each command to the Link-To PC must begin with a command selector byte which selects the required function such as ‘Set dimmer level’ or ‘Set fade rate’.

After each command some number of data bytes must be supplied.

The number of bytes vary for each command and will be described in detail.

Note that the function of the data bytes vary.

Response format of the Link-To PC:

Each valid command successfully received will cause a response be sent.

The rules and format of the responses are the same as the commands.

Each response begins with the 0x3f value followed by a single ASCII character hexadecimal value. This single character value informs about the buffer status of the Link-To PC. The Link-To PC has a 256 byte receive buffer.

The single ASCII character (4 bit) value is always set in each response to indicate the number of 16 byte block used of the receive buffer.

When sending large amount of data to the card this value must be used to throttle the traffic in order to avoid command loss.

After the 0x3f and the buffer indicator (nibble) the result or acknowledge is sent as it was received from the target device. These can be used to detect missed commands.

A missed command would indicate a possible faulty system as the GR2400 Link-To PC attempts to deliver each command several times in case of communication errors.

If no acknowledge or answer is received by the Link-To PC the 0x3f and the usage indicator are still sent followed by an enter character for each command received by the Link-To PC.

COMMANDS:

First things first:

Very important!

The Link-To PC by default relays certain commands from the GR2400 system that are used for fast updates in our system.

If unused this relaying feature should be disabled as they are constantly present and may appear as a ‘bunch of useless data’ at first look.

Instead of having to filter them it is best to send the following command to disable this data stream from the card:

Send the following four ASCII characters: 3820. Then send a carriage return character.

Taking this as an example command this is what it looks like:

The command is 0x38 and is followed by a value 0x20 then ‘enter’.

Note that there is no checksum. This command is to the Link-TO PC itself and not the GR2400 system that is the reason why.

Using the format that the rest of this document uses this command would look like this:

0x38 - 0x20 - <CR> Where we list each byte separated by a ‘-‘ and the enter as <CR>.

In this format Labels (simple names) will be used instead of bytes when describing the format. Each of these labels will be described in detail to show their usage and how to create the byte content that must be sent in place of that label.

Set dimmer fade rate command:

Format: 0x3a - BUSADDR - SEL - FADE2 - FADE1 - FADE0 - Checksum

BUSADDR = The base GR2400 bus address of the target.

SEL = This is a limited value and it selects the target channel of the dimmer as follows:

0x14 = selects channel 1

0x15 = selects channel 2

0x16 = selects channel 3

0x17 = selects channel 4

FADE2,FADE1,FADE0 = These 3 bytes are used combined into one 24 bit value as the fade rate. FADE2 is the most significant byte. Fade rate is given in 60Hz cycle steps.

These functions are available via remote controlling the scenes that are programmed on a particular dimmer. One must first program the proper raise and lower scenes (or know how they are programmed) then remotely emulate the button push and release commands to those scenes. Note: LC & D will dial in and program these scenes for you if you wish.

The suggested/conventional programming would be:

Scene 9: raise channel 1

Scene 10: lower channel 1

Scene 11: raise channel 2

Scene 12: lower channel 2

Scene 13: raise channel 3

Scene 14: lower channel 3

Scene 15: raise channel 4

Scene 16: lower channel 4

In which case one would have to send proper button push and release commands to the corresponding ‘virtual buttons/relay’ of that dimmer.

Raise and lower are usually controlled via a push button where the duration of the button push must be detected in some way.

The method used here is to detect both button push and release event and deliver them individually at the time it happens.

To raise channel 1 (being that above mentioned dimmer programming is done) one would have to send an on/push command to virtual button 9 of the dimmer card then as soon as the source raise button is released the off/release command would have to be delivered to virtual button 9.

The command used for this is 0x05:

On/push and off/release command.

Format: 0x05 – BUSADDR – SEL – Checksum

BUSADDR = The base GR2400 bus address of the target.

SEL = This byte is a dual feature one.

Bit 7 of this byte (MSB) selects on or off function.

0 = off (release)

1 = on (push)

Bits2-0 of this byte select the virtual button as follows:

MSB LSB

000 = selects button 1

001 = selects button 2

010 = selects button 3

011 = selects button 4

100 = selects button 5

101 = selects button 6

110 = selects button 7

111 = selects button 8

Bits6-3 must be ‘0’

Checksum = See the checksum calculation section.

Button selection gets a little tricky so please read this carefully:

Each dimmer panel occupies 2 bus addresses on the GR2400 bus.

The address labeled on the dimmer controller is its base (first) address.

All dimmers occupy the next (one greater) address as well.

Each dimmer has a total of 16 virtual buttons/relays.

The first 8 (virtual buttons -8) are accessible only via the base address.

The second 8 (virtual buttons 9-16) are accessible only via ‘base address’+1.

Thus virtual button 9 of the dimmer card is accessed as button 1 of the second address.

EXAMPLE:

Dimmer is addressed at GR2400 bus address 5. (This is what its label says)

Scene 9 is programmed as channel 1 raise.

To start raising channel 1 of this dimmer one would have to send:

0x05 – 0x06 – 0x80 – 0x8b - <CR>

Then a release must be sent as follows:

0x05 – 0x06 – 0x00 – 0x0b - <CR>

Note that 0x05 is the command. 0x06 is the address as we must operate on the second address occupied by that dimmer which is 0x06. We know this by looking at the dimmers label (in this case 0x05) and incrementing it by one.

The third byte in case of push (raise start) is 0x80. Note that bit7 is ‘1’ and the rest are ‘0’. Thus we select virtual button 1 of the second address which is really virtual button 9 of the whole dimmer. Then we just have the checksum calculated and added.

Important to note that if none of the first 8 virtual buttons are used from the total 16 on the dimmer then ONE MAY view the second 8 as the only set and just simply always add 1 to the address of the dimmer at all times when controlling it.

Thus any relay card that has more than 8 relays will occupy more than one Bus Addresses.

On any relay card take the number of relays and divide it by 8 to get the number of

Bus addresses the card occupies.

E.g.: a GR-2432 occupies 4 Bus addresses.

Note that the Bus addresses occupied by any particular card are always sequential.

To control a relay one must first calculate the address and relay index of that relay.

The base address (lowest value address occupied) of every Relay card is the one

displayed on it. The rest of the addresses are sequential.

Step one is to get the base address of the Relay to be controlled.

The steps to calculate the address offset are based on which Relay is to be controlled.

This can be done as follows:

1. Take the number of the relay.

2. Subtract one from it.

3. Divide that number by 8.

4. The result of the division must be added to the base address.

5. The remainder of the division must be used as the relay index.

EXAMPLE: controlling relay #26 of a GR-2432 card. (that is relay #26 as labeled on the card)

Suppose for this example that this GR-2432 relay card is at Bus address 5.

(That is the number 5 is labeled by that card as the bus address)

GR-2432 cards have 32 relays.

Thus we know that the card will occupy 4 Bus Addresses starting at address 5.

Thus this card occupies addresses 5,6,7 and 8. on the GR-2400 Bus.

The 32 relays of that card can be accessed as follows:

Relay 1-8 can be accessed via Bus address 5.

Relay 9-16 can be accessed via Bus address 6.

Relay 17-24 can be accessed via Bus address 7.

Relay 25-32 can be accessed via Bus address 8.

To control Relay #26 we must:

Take the number 26 and subtract 1 from it.

This is the result of zero referenced indexing which means that

the relays within any address are selected by a number from 0..7.

(it is never 1 through 8 it is always 0 through 7)

After the subtraction we will have the number 25.

To get the Address through which we control that relay we divide this number (25) by 8. (8 is the number of relays per each address)

Thus we get 3 as the result of the division and 1 as the remainder.

To get the address we add the number 3 (result of division) and 5 (the base address) and we get 8. The remainder of the division - number 1 in our example - is used as the relay index which selects which of the 8 relays of that particular BUS address do we manipulate.

Relay On Off commands:

Step one to turn a relay On or Off is to obtain the target address and Relay index of

that Relay.

Please first review the section above labeled as 'Important addressing caveats' including the Example then return to this section.

Once the Target address and Relay index are calculated one can issue an on or off command in the following format:

0x05 - BUSADDR - SEL - Checksum

BUSADDR is the target Bus address of the relay. As calculated in our example above.

SEL is a combined 8 bit field.

The lowest 3 bits (bits 0,1 and 2) select the relay to be operated as follows:

Bits 2 1 0

0 0 0 = 1st relay of that address

0 0 1 = 2nd relay of that address

0 1 0 = 3rd relay of that address

0 1 1 = 4th relay of that address

1 0 0 = 5th relay of that address

1 0 1 = 6th relay of that address

1 1 0 = 7th relay of that address

1 1 1 = 8th relay of that address

Bit 7 of the SEL field selects the required function as '1' for On command and '0' for Off command.