Version 3 has been released!

RemoteSign API Reference

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.

Usually RemoteSign listens for a connection. Once connected, data can be sent to the RemoteSign. The connection is kept open, allowing bidirectional communications. RemoteSigns can also actively make a connection to other devices or to a RemoteSign server.

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, 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
  • Sensor triggers

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.
Attempts to connect with a RemoteSign server will be made on port 50603
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 present its registration status. If it has display capabilities, it will also send you the effective aspect ratios of its screen. 

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 RemoteSign Windows sign itself, you can send {PLAY} commands to play sound effects as needed. Once could also connect to a RemoteSign ESP device simply to listen for sensor information or activate functionality other than the screen.

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. In the syntax definitions, the DC1 is represented by  but it is of course a single byte: hex  11 decimal 17 For example:
    COMMAND}parameter1  parameter2  parameter3....  
  • 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 ␑ OLED
{CH}2 ␑ LM
{CH}3 ␑ E ␑ Bell
{CH}5 ␑ LC
{CH}6 ␑ S ␑ 16

It means there is an OLED screen display, a monochrome light, an event that will ring some bell, 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 ␑ Transition 50.

To ring the bell we send {E}3

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

Some suggested guidelines for adding support for RemoteSign in other software can be found here:https://remotesign.mixmox.com/p/suggestio.html

Command list 

✅ indicates that the command can also be sent by a RemoteSign client

Command

Name
{APPEND}
Append a command while recording
{ASPECT} Screen aspect ratio
{AR}Analog read result
{AR?}
Analog read request
{AUTH} Present or request an auth token
{AUTH?} Request presentation of an auth token
{AW}
Analog write
{BYE}About to disconnect
{CAB}Cab control
{CH} Channel information
{CH?}
Request channel information
{CLEAR}
Clear the screen
{CLOCK}
Configure clock
{DCH}
Define channel
{DIR}
List script files
{DR}Digital read result
{DR?}
Digital read request
{DW}
Digital write
{E}Event
{ERROR}Error message
{HTTP}
Fetch HTTP resource
{IMAGE}
Place an image
{LC}
Color light
{LM}
Monochrome light
{LOAD}Load an .rsf file
{LOG}Send something to be logged
{LOG?}Request log lines
{LOGF}
Flush log
{MSG}Message
{NAME}Software name
{NTP} 
Network Time Protocol
{OTA}
Over The Air update
{PING}Connectivity check
{PLAY}
Play a sound file
{PLAYNONE}
Stop all sound files
{PS}
Store key-value pair
{READY}Ready to receive commands
{RECORD}
Record/end a script
{ROW}
Place text on a screen row
{ROWS}
Set the number of screen rows 
{RUNSCRIPT} 
Run/stop a script
{S}Sensor changed
{SCR}Script list
{SCR?} 
Request a list of scripts
{SCREENLIMITS}
Show the edges of the screen
{SIG}
Set signal aspect or animation step
{SOUND}
Turn sound on or off
{SCROLL}
Place scrolling text on the screen
{SCROLLDOWN}
Move rows down
{SCROLLUP}
Move rows up
{STARTCLOCK}
Start the clock
{STATS}
Request statistics
{STOPCLOCK}
Pause the clock
{STUCK}
Set number of stuck cells
{TEXT}
Place text on a screen
{TIME}
Set the time
{TOKEN}Issue an auth token
{UI}Request display of some UI element
{VER}Version of software
{VW}Virtual write


Sample conversation

indicates a DC1 character (ASCII 17)

Sent by machine AReply from 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}it is ready for commands
{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

RemoteSign Sequencer is the very versatile software for monitoring what commands are arriving and for trying out what commands to send.
Use the log screen to see all commands that are sent and received.
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.

Implementation in train layout control software

Here are some suggestions if you are thinking of adding support to your layout software

Contact

For questions about the API, please contact me at: