You are here: Wiki > start > usertrack > interface_gateway

Locked Page is locked

Table of Contents

Interface Gateway
Introduction
Licensed Simulations
Subscribing
Topics
TD _ ALL _ SIG _ AREA Messages Recieved From The Server
Train Describer (TD)
Signalling Data
Track Circuit Data
Point Data
Signal Data
Route Calls
Ground Frame Data
Level Crossing Data
TD _ ALL _ SIG _ AREA Messages Sent To The Server
Train Describer (TD)
Snapshots
Route Requests & Signal cancellations
Points & Flags
Ground Frame Requests
Level Crossings Requests
SimSig Messages Recieved From The Server
Clock Message
SimSig Messages Sent To The Server
Clock Message / IDRequest
TRAIN _ MVT _ ALL _ TOC Messages Recieved From The Server
Train Location
Train Delay
TRAIN _ MVT _ SUMMARY Messages Received From The Server
TRAIN _ MVT _ SUMMARY Messages Sent To The Server

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 crossings f- predixed 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":"sandhills","clock":50603}}

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

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 23/02/2022 at 17:24