SDK

This page describes the Syntax and data exchange needed to drive a RemoteSign. It is designed for developers who are familiar with software development. I am willing to help with any questions regarding the RemoteSign API but I can't teach you how to program.

Introduction

RemoteSign listens for a connection. Once connected, data can be sent to the RemoteSign. The driving software can set the following:
  • Number of rows to use.
  • For each row, the text content, mask, animation, header colors.
  • Commands to scroll the text lines up and down.
  • Number of stuck cells to use.
  • Time to display.
  • Clock style 12 or 24 hour, and in version 2.2, analog or digital, real time, fast clock, analog clock size and colors.
  • Message information.
  • Error information.
  • Sound file (.wav or .mp3) to play (requires version 2.0).
  • RemoteSign file  (.rsf) to load (requires version 2.0).
  • Scrolling text sign (requires version 2.1)
  • Text areas  (requires version 2.1)

Commands from the RemoteSign can include:
  • Product name.
  • Product version.
  • Aspect ratio of rows to columns.
  • Error messages.
  • Messages.

TCPIP settings

By default, RemoteSign uses TCPIP port 50601. It can however be set to use another port by editing the remotesign.ini file.
Needless to say, the port number used must match that of the RemoteSign.

Expected order of commands

Once your software connects to RemoteSign, it will respond with the product name and version number. It will also send you the effective aspect ratio of its screen. When it is ready to receive data it will send the {READY} command.

It is strongly suggested that you set the desired number of rows before sending any row data.
Once the number of rows has been set, you can send row data in any order you like.

It is important to honor the aspect ratio of rows and columns, since the screen of the RemoteSign may not match that of the machine on which your software is running. Non header rows that have text that is too long will be truncated.

If you are not interested in the sign itself you can send {PLAY} commands to play sound effects as needed.

Command syntax

  • All the commands and responses start with the command name in braces. For example: {ROWS}
  • Any parameters follow the command.
  • If there is more than one parameter, the parameters are separated by the Device Control 1 character (DC1) ASCII character 17. For example:
  • {COMMAND}parameter1 <DC1> parameter2 <DC1> parameter3....  In the syntax definitions below, the DC1 is represented by <DC1> but it is of course a single byte: hex  11 decimal 17
  • Each command must be terminated with a carriage return  ASCII 13
  • Some commands have no parameters.
  • You only need send as many parameters as needed. For example, if a command has 4 parameters and you only need to set the first one, there is no need to send the last 3.

Commands that can be sent to a RemoteSign

{CLEAR} H

Clears (empties) the text from all the lines in the sign. Also removes any text areas placed by the {TEXT} command.
The option H option will also force all lines to black header rows thus forcing the entire screen to be black.

{CLOCK} t

Sets the clock type. t  can be one of these values:
12 = 12 hour clock
24 = 24 hour clock
A = Use Analog clock
D = Use Digital clock
R = Use Real-time clock
F = Do not use real time
Sn = Use n clock speed factor (1 through 5)

In addition the Analog setting can include the analog clock characterstics as follows:

A rows<DC1>ShowSecondHand<DC1>FaceColor<DC1>TickColor<DC1>HandColor<DC1>SecondHandColor
  • rows the number of screen rows that the clock should use. This value should not exceed the number rows of the whole screen set by {ROWS}
  • ShowSecondHand indicates if the analog clock should display a second hand. A "1" means yes, display a seconds hand.
  • FaceColor is an additive decimal RGB color value number that defines the color of the clock face. For example 255 is red. Default is white.
  • TickColor is an additive decimal RGB color value number that defines the color of the hour and minute tick marks. For example 255 is red. Default is black.
  • HandColor is an additive decimal RGB color value number that defines the color of the hour and minute hands. For example 255 is red. Default is black.
  • SecondHandColor is an additive decimal RGB color value number that defines the color of the second hand. For example 255 is red. Default is red.

{ERROR} text

text is an error message. The error will be listed in the log.  The last error message received will be displayed in the connection screen.

{LOAD} file

file The name of a RemoteSign file (.rsf) to be loaded. RemoteSign will first look for the file in the 'rsf' folder contained in the RemoteSign installation folder. If not found it will treat the file name as a fully pathed file reference and try to load it again.

Note that the purpose of the {LOAD} file is primarily to kick off a sequence of chained files.

{MSG} text

text is a non-error message. The message will be listed in the log. The last message received will be displayed in the connection screen.


{NAME} text

text The product name of your software. The name will be displayed in the connection screen.


{PLAY} filename<DC1>alias


  • filename The file name of the sound file to be played. RemoteSign will first try to load the file assuming it contains a fully qualified path. If the file does not exist it will look for the file in the 'Sounds' folder contained in the RemoteSign installation directory. If the filename is empty, then any sound already playing that has the same alias will be stopped.
  • alias An optional alias of your choice. If you later wish to stop the file from playing you can issue a second {PLAY} command with an empty file name and the same alias. The alias is used to tag each playing sound. If you reuse an alias it will cancel the earlier sound with the same alias.

{ROWS} n

Sets the number of rows to n

  • n The number of rows. Must be between 4 and 40
{ROW} n <DC1>text <DC1>mask <DC1>animated <DC1>header <DC1>textcolor <DC1>textbackgroundcolor
Sets the text content for a single row.

  • n is the row number. 1 is the top row. n must be a number from one through the current number of rows
  • text is the text to be displayed
  • mask is the mask text
  • animated indicates if the mechanical sign should be animated or not. A "1" indicates it should be animated.
  • header indicates if the row should  be normal (non mechanical) text or not. A "1" indicates it should be normal text.
  • textcolor is an additive decimal RGB color value number that defines the color of the text, if it is a header line. For example 255 is red.
  • textbackgroundcolor is an additive decimal RGB color value number that defines the background color of the text, if it is a header line.

Possible combinations of animated and header:

Animation

Header

Meaning

1

0

Animated mechanical sign

0

1

Header line

0

0

Non-animated mechanical sign

1

1

*Invalid combination*


{SOUND} 0|1

  • 0|1 Either a zero or a 1. Zero will switch the sounds off and 1 will switch the sounds on.

{SCROLL} n <DC1>text

Sets or removes scrolling text on the indicated row. Requires RemoteSign version 2.1 or higher.
  • n is the row number. 1 is the top row. Use zero to remove an existing scroll line. n must be a number from two through the current number of rows. (The top row cannot be used as the clock is present there.)
  • text is the text to be displayed
Scrolling text scrolls from right to left across the sign and repeats as soon as it has completed traversing the screen. When removed, the original content of the row will once again be visible.

{SCROLLDOWN}

Moves all the lines down one line

{SCROLLUP}

Moves all the lines up one line

{STARTCLOCK}

Restarts the clock

{STOPCLOCK}

Stops (pauses) the clock


{TEXT}index <DC1>text <DC1>row<DC1>column <DC1>width  <DC1>align<DC1>texcolor <DC1>textbackgroundcolor<DC1>size

Positions a text area. Requires RemoteSign version 1.1 or above.
  • index is the index of the text area. It allows the same text to be updated or deleted later. Valid range 1 through 255
  • text is the text to be displayed. If empty, the text area is not displayed. Use this to remove a text area.
  • row is the row in which the text should appear
  • column is the column number of the leftmost edge of the text area
  • width is the width (in columns) of the text area
  • align indicates the alignment of the text:
    L = Left aligned (default)
    C = Centered
    R = Right
  • textcolor is an additive decimal RGB color value number that defines the color of the text, if it is a header line. For example 255 is red.
  • textbackgroundcolor is an additive decimal RGB color value number that defines the background color of the text, if it is a header line.
  • size Percentage of the height of a display row. A value from 1 to 100
If more than one is placed in the same area the last one set will display.

Placing a Text area in a row forces that row to be a header line.
Text areas are not yet saved to disk if the sign is saved.

{TIME} time

Use to set the clock time.
  • time Set the clock time of the RemoteSign clock.
Examples:
{TIME} 13:23
{TIME} 1:23:34 PM

Note: Previous to version 2.2, the {CLOCK} commands changed the computer system time. The RemoteSign clock time can now be independent.

Commands that can be received from a RemoteSign


{ASPECT} aspect*1000

  • aspect is the effective aspect ratio of rows to columns that can be handled. It must be divided by 1000 before being used. This is so that the aspect can be exchanged as an integer and be good to three decimal places - this avoids potential issues with different formatting conventions  between the machines with respect to decimal separators.

For example, an aspect of 625  means an effective aspect of 0.625 which indicates that 25 rows will have 40 columns. 25/40 = 0.625

The aspect takes into account the screen resolution of the remote machine as well as the character cell aspect ratio.
The number of columns has no meaning for header lines.

The first row is always shorter to accommodate the clock, status lights, etc. Subtract 11 for row 1.

{ERROR} text

  • text is an error message

{MSG} text

  • text is a non-error message

{NAME} text

  • text The product name. RemoteSign.

{READY}

The RemoteSign is ready to accept commands

{TIME} time

Use to synchronize the system time of the two machines.
  • time Indicates the time that should be set.
Example:
{TIME} 16:9:48

{VER} text

  • text The version of the RemoteSign. Text.

Sample conversation

indicates a DC1 character (ASCII 17)
Sent by machine ASent by machine B (running RemoteSign)What machine B does
{NAME}Lucky Sign companyDisplay this name in the connection dialog
{VER}2.4Display this in the connection dialog
{NAME}Remote SignResponds with it's own name
{VER} 1.0and version
{ASPECT} 625and indicates that the number of columns it can handle is rows/0.625
{READY}and is ready to receive data
{ROWS} 20Resize its rows so that there are 20 lines and 20/0.625 = 32 columns
{ROW} 1RemoteSign701 65535 0Display header text in row 1
{ROW} 2␑␑700 33023 0Display a blank row 2
{ROW} 3        W E L C O M E !710 16711680 0Display animated text in line 3
{ROW} 4␑␑701 65535 0Display a blank row 4
{ROW} 5 PRESS ENTER TO ALTER TEXT710 0 0Display animated text in line 5
{ROW} 6   OR CONNECT TO ANOTHER S710 0 0Display animated text in line 6
{ROW} 7␑␑700 65535 0Display a blank row 7
{ROW} 8attention getting...701 65280 0Display header text in row 8
{ROW} 9                easy remote signage701 255 16777088Display header text in row 9
{TIME}16:9:48Set the remote clock time to 4:09:48 PM
{MSG}Don't PanicDisplay Don't Panic in the log and last message area of the connection screen (when displayed)
{CLOCK}24Set the time display to use 24 hour clock


Testing and Debugging

Use the log screen to see all commands that are sent and received by RemoteSign.
You can also use the manual command feature in the Connection screen to send commands to either another copy of RemoteSign or your software.

Performance

When implementing support for RemoteSign try to be considerate for people who may only have a low powered machine to run RemoteSign. Flooding RemoteSign with a large number of animated text rows will place a large load on the machine especially if the animated sound effects are enabled. If possible, try to make a number of smaller screen updates.