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. 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 allow an Arduino or ESP type device code to provide a summary of supported characteristics and also 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: {ML}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)

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

{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 {DV} command

{DW}pinvalue

Set an output pin (GPIO) output to a value. (Using digitalWrite();)


  • pin is the pin be set  For example {P1}0 will set pin 1 to zero
  • value is the value to use. 255 would be high, zero would be low and 1 through 254 are  pulse width values

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

{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

Note: it is important to add some part (the rest of the path) of the URL in the code or protect it with a password to prevent someone from replacing the firmware with malicious code.

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

{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


{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

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