Guidelines for entering serial codes

This section describes the different formats you can enter for the serial data of each command in Control4 serial drivers.

These formats include:

  • Basic Method to Enter Bytes—Shows you how to enter a basic code.
  • Method to Enter Delays—Shows you how to enter a delay code that you need to control some devices.
  • Method to Enter Parameters—Shows you how to enter the needed parameters.
  • Method to Enter Checksums—Shows you how to enter the checksums.

    • Method

    Description

    Basic Method to Enter Bytes

    All serial data in the end becomes bytes. There are three basic formats to represent bytes, but in the end the resulting data is just bytes, and any format would suffice for the entry. For ease-of-use, multiple formats are supported.

     

    Examples for all methods: Data is equivalent to the ASCII string “DVD” with a carriage return at the end.

     

    Decimal Data—With decimal data and between any of the different formats there must be a space to act as a delimiter between different pieces of data. To enter decimal data, enter the value to be stored in the byte in decimal. Valid data is from 0-255.

     

    Example: Data (“DVD” with carriage return):

     

    68 86 68 13

     

    Hexadecimal Data—With hexadecimal data and between any of the different formats, there must be a space to act as a delimiter between different pieces of data. To enter hexadecimal data, enter the ‘$’ symbol immediately followed by the value to be stored in the byte in hexadecimal. Valid data is from $00-$FF.

     

    Example: Data (“DVD” with carriage return):

     

    $44 $56 $44 $0D

     

    ASCII Data—All ASCII data must be inside double quotes. Each byte inside the quotes represents one byte of data. Look at any ASCII table to see the real values each character represents. The same ASCII characters supported in the C programming language are supported. Escape characters are also supported in the same way. Supported characters include \n (new line), \r (return), \t (tab, and \” (double quotes).

     

    Example: Data (“DVD” with carriage return):

     

    “DVD\r”

     

    Mixing formats — All of the above formats can be used together, and the person can use whichever seems most efficient.

     

    Example Data (All examples represent the exact same data):

     

    “DVD” $0D

    68 “VD” 13

    “DV” $44 13

    $44 $56 68 13

    68 $56 68 “\r”

    Method to Enter Delays

    Many times it is necessary to create delays when sending data to a serial device. The ‘#’ character is used to represent that the following number is a delay in milliseconds. A space is required between each element in the data.

     

    Example: This example assumes that the protocol calls for a “PWON\r” command followed by a 1500 millisecond delay followed by a “PLAY\r”.

     

    ASCII Example:

     

    “PWON\r” #1500 “PLAY\r”

     

    Decimal Example:

    80 87 79 78 13 #1500 80 76 65 89 13

    Method to

    Enter Parameters

    Many commands have parameters. Examples of these commands are the GO_TO_CHANNEL command for TVs and Satellite receivers or GO_TO_DISC commands for DVD and CD changers.

     

    During driver creation, you are allowed to create macros to embed the parameter in the data that is being entered. This creates different problems depending on whether the protocol is a binary or ASCII protocol. When entering ASCII parameters, use a modified version of the format that C uses in its printf function.

     

    Example: This example is a GO_TO_CHANNEL command where the protocol specifies that the devices need the ASCII command “Channel XXX\r” where the XXX is the three digit (decimal) channel number that is being requested with zeroes padded (on the left) if the number is less than 100. The parameter name is CHANNEL_NUMBER.

     

    ASCII Example:

     

    “ChannelHarman Kardon03dCHANNEL_NUMBER \r”

     

    Later, at run time when this command is called with the Channel 56, the output appears as follows:

    “Channel 056\r”

     

    During driver creation, you can also enter parameters in a binary protocol format. Borrowing from the last format with the modification that following the%, first is the byte count (valid counts are 1, 2 and 4), followed by the byte order (E = big endian, e = little endian), followed by the data format (D = decimal, others to follow). This is obviously followed by the actual parameter name as in the example above.

     

    Example: This example assumes the protocol needs a start byte that is the number 2, followed by the GO_TO_CHANNEL command code which is 57, followed by a 2-byte big endian channel number, followed by the end byte which is 0.

     

    2 57%2EDCHANNEL_NUMBER 0

     

    Later on at run time when this command is called with the Channel 357 the output looks like the following using our format.

     

    2 57 1 101 0

    (Hint 0x0165 is hexadecimal for 357, and 1 = 1 in decimal and 65 = 101)

     

    If the protocol used little endian for the parameter, the data entry is:

     

    2 57%2eDCHANNEL_NUMBER 0

     

    The output for the previous example is:

     

    2 57 101 1 0

    Method to Enter Checksums

    Many protocols require a calculated checksum. A way must be provided for the user to calculate a checksum. There are several formats for checksums, so different types of checksums must be allowed. The ‘&’ signifies that the software needs to enter a checksum followed by a byte count (valid counts are 1, 2, and 4), followed by the byte index in the command where the checksum calculation starts (valid numbers are 0-9), followed by the byte size of the checksum chunks (valid sizes are 1 and 2), followed by byte order (E = big endian e = little endian), followed by the checksum calculation format (STD = standard (chunk size wide) addition inverted, CRC = CRC).

     

    Example: The example uses the same devices as previously mentioned and assumes the big endian GO_TO_CHANNEL command, where that command needs a checksum (before the 0 end byte) starting at the beginning of the command, and the command is a simple 1-byte checksum.

     

    The data entry displays the following:

     

    2 57%2EDCHANNEL_NUMBER &101ESTD 0

     

    And the output for the previous examples is (channel = 357):

     

    2 57 1 101 94 0