You are here: Wiki > start > usertrack > interface_gateway

---

Page is locked

Interface Gateway

Introduction

The SimSig Interface gateway allows SimSig to generate messages to the outside world in a specific format similar to that of the Network Rail Open data feeds.

This page aims to document the uses of Interface Gateways, and the format of messages that SimSig produces.

Licensed Simulations

When connecting to a gateway generated from a simulation which requires a license, you will need to authenticate in the connect frame, or connect message with the credentials of a SimSig account which holds a valid license. You may experience a short delay in connecting while the license is authenticated with the SimSig licensing server.

Subscribing

In order to receive messages from the interface gateway you will need to have some sort of STOMP client.

You will need to subscribe to the following topic(s).

topic:TD_ALL_SIG_AREA

topic:TRAIN_MVT_ALL_TOC

topic:SimSig

topic:TRAIN_MVT_SUMMARY

An example STOMP client written in Python 2.7 can be found On Headshot119s Github . Please note this is a very basic client designed only to print messages received onto the standard output.

Topics

Topic Name	Description
TD_ALL_SIG_AREA	Provides information on TD steps, and the state of the signalling equipment. It is also used to send certain requests to the simulation.
TRAIN_MVT_ALL_TOC	Provides information on train movement within the simulation.
SimSig	Provides heartbeat messages at a minimum of every simulated minute.

TD_ALL_SIG_AREA Messages Recieved From The Server

Each of the messages that can be sent by the simulation server, to connected clients on the gateway are documented in this section.

Train Describer (TD)

Train Describer messages give information about the state of the Train Describers in the simulation.

There are three messages message types.

Message Format

Messages are sent in JSON format.

{"CA_MSG":{"area_id":"north_wales_coast","from":"GN17","to":"BR60","descr":"2R43","msg_type":"CA","time":"566"}}

{"CB_MSG":{"area_id":"north_wales_coast","from":"BR60","descr":"2R43","msg_type":"CB","time":"668"}}

{"CC_MSG":{"area_id":"north_wales_coast","to":"GN17","descr":"2R43","msg_type":"CC","time":"456"}}

Message Types

Type	Name	Notes
CA	Berth Step	Description steps from the "from" berth, to the "to" berth.
CB	Berth Cancel	Description steps from the "from" berth to nowhere.
CC	Berth Interpose	Description steps into the "to" berth from nowhere.

Message Fields

Field	CA	CB	CC	Notes
area_id	T	T	T	Simulation the message was sent from. Note the format is the .sim file name
from	T	T		ID of the TD berth the description was stepped from. GN17 - Gaerwen 17
to	T		T	ID of the TD berth the description was stepped to. BR60 - Bangor 60
descr	T	T	T	The string that stepped. 2R43
msg_type	T	T	T	The type of message.
time	T	T	T	Time the message was sent. Measured in seconds from midnight. "time":"566" = 00:09:26

In certain simulations, it is possible that the TDs shown on the screen are not what is shown in the data feeds. This can be noted specifically around approach berths, where one berth may cover what the simulation sees as several within the data.

Signalling Data

Signalling data messages give information about the state of points, track circuits, signals, routes and some other data. Each one is described in detail.

Message Types

Type	Name	Notes
SG	Signalling Refresh	Updates an object's state

All signal data messages are of type SG.

Track Circuit Data

Message Format

{"SG_MSG":{"area_id":"north_wales_coast","obj_id":"TLJ176","obj_type":"track","clear":"False","msg_type":"SG","time":"2975"}}

{"SG_MSG":{"area_id":"north_wales_coast","obj_id":"TLJ176","obj_type":"track","clear":"True","msg_type":"SG","time":"3010"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the track circuit prefixed with "T"
obj_type	The type of object
clear	True - Track Clear, False - Track Occupied
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"2975" = 00:49:35

Point Data

Message Format

{"SG_MSG":{"area_id":"north_wales_coast","obj_id":"PLJ451","obj_type":"point","dn":"False","dr":"True","cn":"False","cr":"True","kn":"False","kr":"False","msg_type":"SG","time":"5967"}}

Message Fields

Note messages are received for each point end. A crossover will therefore generate two messages.

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the point prefixed with "P"
obj_type	The type of object
dn	True - Detected normal, False - Not Detected normal
dr	True - Detected reverse, False - Not Detected reverse
cn	True - Called normal, False - Not Called normal
cr	True - Called reverse, False - Not Called reverse
kn	True - Keyed normal, False - Not Keyed normal
kr	True - Keyed reverse, False - Not Keyed reverse
locked	True - Locked and unable to move, False - Free to move
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"5704" = 01:35:04

Signal Data

Message Format

{'SG_MSG': {'area_id': 'aston', 'obj_id': 'SAN126', 'obj_type': 'signal', 'aspect': '0', 'bpull': 'False', 'rset': 'true', 'appr_lock': 'False', 'lp': 'true', 'auto': 'False', 'trts': 'False', 'stackN': 'False', 'stackX': 'False', 'msg_type': 'SG', 'time': '70'}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the signal - predixed with "S"
obj_type	The type of object
aspect	Aspect the signal is displaying. See Aspect chart for details
bpull	Was the signal cancelled by the user. True / False
rset	Is a route set from the signal True / False (always True for auto signals and repeaters
appr_lock	Is the signal approach locked. True / False
lp	Is the signal lamp proved. True / False
auto	Is the auto button set (for controlled signals), or emergency replacement button not pressed (ie automatic signal allowed to show proceed). True / False
trts	Is the TRTS associated with this signal flashing? True / False
stackN	True / False
stackX	True / False
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"5704" = 01:35:04

Aspect Chart

Number	Aspect
0	Red
1	Shunt
2	Yellow
3	Flashing Yellow
4	Double Yellow
5	Flashing Double Yellow
6	Green

Note that a signal which is out will report the aspect that it should be showing, but lamp proving will go false.

=

Flag Data

Flags are used in SimSig for various things. In this example this flag is used to control the state of the Abergele - Rhyl Absolute Block Train On Line lights (0 Off, 1 On)

Message Format

{"SG_MSG":{"area_id":"north_wales_coast","obj_id":"LAERHTL","obj_type":"flag","state":"1","msg_type":"SG","time":"5704"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the flag - prefixed with "L"
obj_type	The type of object
state	The value of the flag. Can be 0 - 63. Generally 0 is false, 1 is true.
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"5704" = 01:35:04

Route Calls

Route calls are detailed in several lines of events, most of which have been detailed above.

The Route Call

Message Format

{"SG_MSG":{"area_id":"north_wales_coast","obj_id":"RAE59AM","obj_type":"route","is_set":"True","msg_type":"SG","time":"32"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Is the name of the route, prefixed R. Generally speaking the left hand most route will be A (or 1) with Z (or 26) being the right most route. The last latter indicates the class of route. M - Main, S - Shunt, C - Call on, V - Virtual
obj_type	Type of Object (Route)
is_set	Has the route been set? True / False
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"182" = 00:03:01

Indicating Reserved Tracks

When a route is called, the route is indicated in SimSig by white subroute lights (one track will contain one locked subroute; one subroute exists in exactly one track). These messages are outlined as:

Message Format

{"SG_MSG":{"area_id":"north_wales_coast","obj_id":"ULJ176-BA","obj_type":"ulc","locked":"False","overlap":"","msg_type":"SG","time":"32"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	The sub-route of the track which has been called. The last two letters indicate which ends of the track circuits have been lit up, and the order in which they where lit.
obj_type	Type of object (ulc)
locked	Whether the subroute is locked. True / False
overlap	Whether the subroute is locked as part of an overlap (True) or as part of the main route (False) True / False
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"32" = 00:00:32

Ground Frame Data

Message Format

{"SG_MSG":{"area_id":"porttalbot","obj_id":"F846","obj_type":"frame","release_given":"True","release_taken":"True","reminder":"False","msg_type":"SG","time":"242"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the ground frame release - predixed with "F"
obj_type	The type of object
release_given	Whether the release is given or not
release_taken	Whether the ground frame operator has taken the release which is given
reminder	Whether a reminder appliance is placed on the ground frame
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"5704" = 01:35:04

Level Crossing Data

Level crossing data is split into two distinct types, data for controlled crossings, and data for AHB crossings. These are documented here separately.

Message Format for controlled crossings

{"SG_MSG":{"area_id":"sandhills","obj_id":"GHE","obj_type":"crossing","state":"0","lower_reminder":"False","raise_reminder":"False","clear_reminder":"False","auto_lower":"False","request_lower":"False","request_raise":"False","blocked":"0","msg_type":"SG","time":"17"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the crossing prefixed with "G"
obj_type	The type of object
state	0 - Up, 1 - Lowering, 2 - Down, 3 - Clear, 4 - Raising
lower_reminder	A reminder appliance is applied to the lower control
raise_reminder	A reminder appliance is applied to the raise control
clear_reminder	A reminder appliance is applied to the clear control
auto_reminder	A reminder appliance is applied to the auto raise control
auto_lower	Whether auto lower is on or off
request_lower	Whether a lower request has been made
request_raise	Whether a raise request has been made
blocked	Whether the crossing is blocked by a road vehicle
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"5704" = 01:35:04

Message Format for AHB crossings

{"SG_MSG":{"area_id":"sandhills","obj_id":"HCR","obj_type":"ahb","state":"0","user_state":"0","tel_message":"12","reminder":"False","failed":"False","failed_ack":"False","msg_type":"SG","time":"0"}}

Message Fields

Field Name	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
obj_id	Name of the ground frame release - predixed with "H"
obj_type	The type of object
state	0 - idle, 1 - Delayed in lowering, 2 - amber lights, 3 - red lights, 4 - barriers down
user_state	###TBA###
tel_msg	###TBA###
reminder	Whether a reminder appliance is applied
failed	Whether the crossing has failed or not
failed_ack	Whether the failure of the crossing has been acknolwedged
msg_type	The type of message.
time	Time the message was sent. Measured in seconds from midnight. "time":"5704" = 01:35:04

TD_ALL_SIG_AREA Messages Sent To The Server

Each of the messages that can be sent by the client to the server, are documented in this section.

Train Describer (TD)

Train Describer messages allow you interpose, cancel, or step a description.

Message Format

Messages are sent in JSON format.

{"ca_msg":{"from":"HJ9","to":"HJ13","descr":"1234"}}

{"cb_msg":{"from":"HJ10"}}

{"cc_msg":{"to":"HJ6","descr":"TEST"}}

Message Types

Type	Name	Notes
CA	Berth Step	Description steps from the "from" berth, to the "to" berth.
CB	Berth Cancel	Description steps from the "from" berth to nowhere.
CC	Berth Interpose	Description steps into the "to" berth from nowhere.

Message Fields

Field	CA	CB	CC	Notes
from	T	T		ID of the TD berth the description is to step from.
to	T		T	ID of the TD berth the description is to step to.
descr	T	T	T	The string that is to be stepped.

Snapshots

When connecting to a simulation, it is possible to request a "dump" of the current simulation state using a snapshot.

Messages are sent in JSON format.

{"snapshot":{}}

Message Types

Type	Name	Notes
snapshot	Snapshot	Request the simulation send a snapshot of all current object states

Message Fields

This wil cause the simulation to reply with a large quantity of data documented above for all objects in the simulation.

Route Requests & Signal cancellations

Route request messages allow you to set routes, either by knowing the route ID, or by inputting a pair of signals.

Message Format

Messages are sent in JSON format.

{"routerequest":{"route":"RHJ1AM"}}

{"routerequest":{"fromSignal":"SHJ3","toSignal":"SHJ5"}}

{"bpull":{"signal":"SHJ10"}}

Message Types

Type	Name	Notes
routerequest	Route Request	Request the simulation set a route
bpull	Cancel Signal	Request the simulation cancel a route

Message Fields

Field Name	Notes
route	The route for the simulation to attempt to set.
fromSignal	The signal which will form the entry signal of a route request.
toSignal	The signal which will form the exit signal of a route request.
signal	The signal which will be cancelled as part of the request.

Points & Flags

Point and flag messages allow you to change the position of points, and to set the state of flags within the simulation.

Message Format

Messages are sent in JSON format.

{"sigobjstate":{"object":"PHJ33A","keyN":"1"}}

{"sigobjstate":{"object":"PHJ33B","keyR":"1"}}

{"sigobjstate":{"object":"LWHJINTCON","state":"true"}}

Message Types

Type	Name	Notes
sigobjstate	Route Request	Request the simulation set a route
bpull	Cancel Signal	Request the simulation cancel a route

Message Fields

Field Name	Notes
object	The object on which to perform the action.
keyN	Change the Normal key state (1 to key to normal, 0 to remove the key)
keyR	Change the Reverse key state (1 to key to reverse, 0 to remove the key)
state	Change the state of the flag (true or false) OR a numerical value 0 - 63

Ground Frame Requests

A groundframe request allows you to release, or normalise a ground frame control.

Message Format

Messages are sent in JSON format.

{"framerelease":{"frame":"F836","release":"True"}}', destination='/topic/TD_ALL_SIG_AREA')

Message Types

Type	Name	Notes
framerelease	Frame Release Request	Request the simulation release a frame

Message Fields

Field Name	Notes
frame	ID of the groundframe to release
release	True to release, or False to normalise

Level Crossings Requests

A level crossing request allows you to send commands to controlled level crossings. These are generally the crossings in simulations which have raise, lower, clear, and optionally auto raise controls

Message Format

Messages are sent in JSON format.

{"crossingrequest":{"crossing":"GPENCOED","operation":"raise"}}

{"crossingauto":{"crossing":"GPENCOED","autoraise":"False"}}

Message Types

Type	Name	Notes
crossingrequest	Crossing Control Command	Request the simulation lower, raise, or clear a crossing
crossingauto	Crossing Auto Raise Toggle	Request the simulation toggle the auto raise control

Message Fields

Field Name	Notes
crossing	ID of the level crossing
operation	raise, lower, or clear [Only for crossing request]
autoraise	True or Fale [Only for auto raise request]

SimSig Messages Recieved From The Server

Each of the messages that can be sent by the simulation server, to connected clients on the gateway are documented in this section.

Clock Message

Train Describer messages give information about the state of the Train Describers in the simulation.

Clock Messages give information about the current simulation time, as well as the simulation ID that sent the information

There is one message types.

Message Format

Messages are sent in JSON format.

{"clock_msg":{"area_id":"aston","clock":2,"interval":500,"paused":true}}

Message Types

Type	Name	Notes
clock_msg	Clock Update	Current time, and simulation ID from which the message was sent. This message is sent every simualted minute, on pause / unpuase, and everytime the simulation speed is changed.

Message Fields

Field	Notes
area_id	Simulation the message was sent from. Note the format is the .sim file name
clock	Simulation time when the message was sent. Measured in seconds from midnight. "time":"50603" = 14:03:23
interval	The speed of the simulation
paused	True or False, whether the simulation is paused or not (Needs loader 5.22 onward)

SimSig Messages Sent To The Server

Each of the messages that can be sent by the client to the server, are documented in this section.

Clock Message / IDRequest

It is possible to send a message to the gateway to request the current time, and also the ID of the simulation being run to be sent back.

Messages are sent in JSON format.

{"idrequest":{}}

Message Types

Type	Name	Notes
idrequest	ID Request	Request the simulation send clock message containing the current time, and simulation ID

TRAIN_MVT_ALL_TOC Messages Recieved From The Server

Each of the messages that can be sent by the simulation server, to connected clients on the gateway are documented in this section.

Train Location

Train location messages give information about the movement of trains within the simulation. Both passing individual signals, as well as passing timing points in the simulation.

There is one message types.

Message Format

Messages are sent in JSON format.

{"train_location":{"headcode":"2C29","uid":"4","action":"pass","location":"S717","platform":"","time":50893,"aspPass":6,"aspAppr":6}}

Message Types

Type	Name	Notes
train_location	Train Location	A status update about an individual trains location within the sumuation

Message Fields

Note when passing a timing point information on signal aspects are not recieved.

Field	Notes
headcode	Headcode of the train in question
uid	UID of the train within the simulation, this is not the same as the timetable UID
action	Whether the train arrived, departed, or passed the location. arrive, depart, pass
location	The location passed, either a signal ID prefixed with "S" or the TIPLOC of the location
platform	Platform at the location
time	Time the message was sent. Measured in seconds from midnight. "time":"50893" = 14:08:13
aspPass	Aspect encountered on passing the location
aspAppr	Aspect encountered approaching the location

Train Delay

Train delay messages give information about any delays to trains that the simulation has recorded.

There is one message types.

Message Format

Messages are sent in JSON format.

{"train_delay":{"headcode":"2W31","uid":"Y61125","delay":180}}

Message Types

Type	Name	Notes
train_delay	Train Delay	A status update about an individual trains delay within the sumuation

Message Fields

Field	Notes
headcode	Headcode of the train in question
uid	UID of the train within the simulation, this is not the same as the timetable UID
delay	The current calculated delay of the train in seconds. A negative value is early running.

TRAIN_MVT_SUMMARY Messages Received From The Server

Each of the messages that can be sent by the simulation server, to connected clients on the gateway are documented in this section.

* This section requires completion following release of loader 5.18 or greater

TRAIN_MVT_SUMMARY Messages Sent To The Server

Each of the messages that can be sent by the client to the server, are documented in this section.

* This section requires completion following release of loader 5.18 or greater

---

Last edited by headshot119 on 04/10/2022 at 17:00