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

Originally, RemoteSigns were only display devices. The RemoteSign commands set has over time been enhanced to also handle devices that do things other than display signs. For example it can be used to play sound effects or control ESP8266 devices which allows almost any functionality that can be implemented via an ESP8266 device.

RemoteSign listens for a connection. Once connected, data can be sent to the RemoteSign.

The driving software can set the following for RemoteSigns that have display capabilities:
  • 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)
In addition, other RemoteSigns can be sent commands to activate events, write pins to ESP8266 devices, etc.

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

TCPIP settings

By default, RemoteSign uses TCPIP port 50601. On Windows, 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. If it has display capabilities, it will also send you the effective aspect ratios 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.

Channels

Channels allows a RemoteSign to provide a summary of supported capabilities which in turn allows specific features to be controlled at a high level. For example, the device may report the following channels.


{CH}1 ␑ LM
{CH}2 ␑ LM ␑ D
{CH}3 ␑ E ␑ Bell
{CH}4 ␑ NEO ␑ 34
{CH}5 ␑ LC
{CH}6 ␑ S ␑ 16


It means there is a non-dimmable monochrome light, a dimmable monochrome light, and event that will ring some bell, a 34 light NeoPixel string, a color light, and 16 sensors are available. (Rather an extreme example for current hardware.) The software talking to the device does not have to know about specific pins and low level operations at all.


In order to set the monochrome light on channel 2 to 50% brightness we simply send: {LM}2 ␑ 50.
To ring the bell we send {E}3


The connection can expect to potentially receive {S}1 through {S}16 sensor reports

Commands that can be sent to a RemoteSign (in Alphabetical order)

{AR?}pin

Request the value of an analog input pin (GPIO) (Using analogRead();)

  • pin is the pin be read  For example {AR}1 will request the value of pin 1
The value will be returned in a {AR} command

{AW}pin ␑ value

Set an output pin (GPIO) output to a value. (Using analogWrite();)
  • pin is the pin be set  For example {AW}1 ␑ 20 will set pin 1 to 20
  • value is the value to use. 255 would be always on, zero would be always off and 1 through 254 are  pulse width values

{BYE} 

Can be used to tell the RemoteSign that we are about to disconnect.


{CAB}  property  ␑ value

Set a loco cab data item when used with model train control software.
  • property the name of the property data being sent
From layout software only
  • L Speed Limit Eg 80
  • H Signal aspect Eg Hp2Vr0
  • S speed DC2 desired speed
  • I image URL
  • F Function name list
  • f Function state list
From CAB or layout software
  • D Direction 1 = forwards 0 = reverse
  • n Function state Eg 5 ␑ 1 means f5 is on
  • P Power 0 = off 1 = on 2 = halt
  • 8 Ignore s88 0 = off 1 = on
  • M Manual control 0 = off 1 = on
From CAB only
  • E Execute event, return integer that is the n’th event given to the CAB
  • T Train number = register the cab with that train -1 = release train
  • G set desired (goal) speed
  • S Emergency stop train
  • d Dispatch station dc1 track dc1 destination
  • k Set k83/4. Address ␑ R/G


  • value the new value. To set multiple values (Eg for a menu), separate the items with ␒ characters.

One CAB is allowed per per device, so no need for channel information on every command. (Can still have additional channels that are not CABs)
{CAB} commands can be sent and received from the RemoteSign.

For example:
{CAB} S ␑ 23 ␑ 40
{CAB} F ␑ lights ␒ smoke
{CAB} f ␑ 1 ␑ 1
{CAB} I ␑ http://example.com/images/34.jpg
{CAB} H ␑ Vr0
{CAB} D ␑ 0
{CAB} L ␑ 8

Example conversation between server (right) and RemoteSign with a cab control (left)
{CH}1 ␑ CAB
{LT} Train 1 ␒ Train 2 ␒ Train 3
{CAB}T ␑ 2
{CAB}F ␑ lights ␒ smoke
{CAB}f ␑ 1 ␑ 1
{CAB}S ␑ 23 ␑ 40
{CAB}I ␑ http://example.com/images/34.jpg
{CAB}H ␑ Vr0
{CAB}D ␑ 0
{CAB}L ␑ 80
{CAB}G ␑ 80
{CAB}S ␑ 24 ␑ 80
{CAB}I ␑ http://example.com/images/35.jpg
{CAB}H


{CH?} 

Request channel capability information from a connected client
See
{CH} command for responses.


{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
N = No clock display
Sn = Use n clock speed factor (1 through 5)

In addition, the Analog setting can include the analog clock characteristics 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.
Notes
The No clock display option is supported by RemoteSign ESP 1.2.1 and later

{DR?}pin

Request the value of a digital input pin (GPIO) (Using digitalRead();)

  • pin is the pin be read  For example {DR}1 will request the value of pin 1

The value will be returned in a {DR} command

{DW}pinvalue

Set an output pin (GPIO) output to a value. (Using digitalWrite();)
  • pin is the pin be set  For example {DW}1 ␑ 0 will set pin 1 to zero
  • value is the value to use. 1 means high (on), zero means low (off)

{E} ch params

Cause the Event defined by channel 1 to be carried out


  • ch is the channel action to be performed.  For example {E}1 will request the event associated with channel 1 to be executed.
  • params (optional) any parameters that the event would like to receive.


{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.

{LC} ch color duration

Set a color light set to a color


  • ch The channel to change.
  • color an additive decimal RGB color. The RGB values will also control the brightness. 0 = off
  • Duration time in seconds to transition to the new setting


{LM} ch bri duration

Switch a monochrome light set to a brightness level


  • ch The channel to change.
  • bri For monochrome lights the brightness percentage from 0 to 100. 0 = off
  • Duration time in seconds to transition to the new setting



{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.

{LOG?} n

Requests n lines of a log. The lines request shoudl be sent using a {LOG} command and ended with a {LOGF}


{LOG} logtext

Sends a line of text to be appended to a log display on the other RemoteSign


  • logtext text content of a log



{LOGF}

Informs the other RemoteSign that there are no more {LOG} lines to be sent in response to a {LOG?} request.

Note for {LOG?}, {LOG} and {LOGF}

These three command are usually used to fetch a list of items from a RemoteSign server. For example a train layout control software may maintain a log. A RemoteSign client may wish to view the log, it can request the last n lines using the {LOG?} command. The server then sends as many {LOG} commands as are needed and then sends a {LOGF} to let the requester know that they have all been sent, so that it can display the lines at its end.

{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.

{OTA} name

Over The Air firmware update.
  • name The name of the software image that should be installed. Not supported on Windows. Supported on devices such as ESP8266.
For example: {OTA}version8.bin

{PING} 

A command that is ignored. This is useful for checking to see if  the remote RemoteSign is still running. If it has disconnected a communication result will likely occur, indicating that the connection has been dropped. The {PING} command does not wake the screen dimmer if it has activated.

{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.
Only supported on Windows.

{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 one through the current number of rows.
  • 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.

{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.

{VW}pin value

Set a virtual output pin to a value. (Typically used with Blynk apps)

  • n is the pin be set  For example {VW}1 ␑ 0 will set  V1 to zero
  • value is the value to use. It can be any value accepted by the virtual pin, including strings.

Commands that can be received from a RemoteSign

{AR}pin ␑ value

Report the result of an analogRead() of a pin, in response to a {AR?} command

  • pin  is the GPIO pin number
  • value  is the value of the pin

{ASPECT} aspect*1000

  • aspect is the effective aspect ratio of rows to columns that can be handled. This includes the aspect ratio of the screen.
Note: The ratio 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 number of columns can be approximated with (rows / aspect)

The number of columns has no meaning for header lines, which use proportional fonts.

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

{CH}ch type param

Defines a channel that is available on the remote device.
  • ch the number of the channel
  • Type the channel type. One of the following
    • A = Audio
    • CAB = Cab control
    • E = A predefined event
    • LCD = Text only sign, (typically a monochrome LCD screen)
    • LC = Color Light
    • LM = Monochrome Light
    • NEO = Neopixel type strings with addressable lights
    • R = RemoteSign with color display, clock, audio, etc.
    • S = Sensors
    • OLED = OLED display (RemoteSign with limited capabilities)
    • TTS = Text to speech (Speech synthesis)
  • Param
    • For type E, the name of the event (optional)
    • For type MONO, a D indicating dimmable  optional name
    • For type NEO, light range from  to end  optional name
    • For type S, the number of sensors available
    • For type TTS, TBD Languages available?  (optional)
    • For types LCD, and OLED,  rows  columns   optional name


Notes:

  1. Channel numbers are expected to be contiguous and start at 1.
  2. To enable backward compatibility, traditional RemoteSigns and OLED signs must report on channel 1. (So if Channel 1 is not an R it is not a traditional RemoteSign.) Conversely all RemoteSign commands are regarded as being for channel 1.

Examples:


{CH}1␑ R
A classic RemoteSign

{CH}1 ␑ LM
{CH}2 ␑ LM ␑ D
A system with two independent lights, one is dimmable

{CH}1␑ E ␑ Turntable position 3
Sending an {E}1 command will set the turntable to position 3

{CH}1␑ LCD ␑ 2  20
Channel 1 drives a 2 row 20 column LCD display

{CH}1␑ NEO ␑ 0 ␑ 12
{CH}2␑ NEO ␑ 13 ␑ 13
{CH}3␑ NEO ␑ 14 ␑ 20
{CH}4␑ NEO ␑ 18 ␑ 20
A set of NeoPixel strings in 4 channels. Note Neopixels may ‘belong’ to more than one channel. They could be separate strings or all in one physical string


{DR}pin ␑ value

Report the result of a digitalRead() of a pin, in response to a {DR?} command

  • pin  is the GPIO pin number
  • value  is the value of the pin. 1 means HIGH, 0 means LOW


{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

{S}sensor ␑ state

Use to report the change of a sensor state
  • sensor Indicates the sensor number
  • state indicates the state, either  1 or 0
Example:
{S}1 ␑ 1

Note: The Windows version 2.5.2, and higher, of RemoteSign will attempt to load a file in the form SensornOn.rsf or SensornOff.rsf when it receives a {S} command. This allows a RemoteSign ESP to send sensor data to the Windows RemoteSign and thus have the screen content changed in response.

For example,
{S}2 ␑ 1
would cause RemoteSign to load a file called Sensor2On.rsf if it is present. 
{S}2 ␑ 0
would cause RemoteSign to load a file called Sensor2Off.rsf if it is present. 

No {ERROR} command is sent if the file is absent.

The Windows version 2.6 and higher will send sensor commands S1 through S10 if the number keys 1 through 9 and 0 are pressed.


{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.
Another tool you can use is Putty

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.