GIPSIE ® (7.0.0)

# Run-time API

GIPSIE® offers an API to receive run-time settings over a TCP/IP connection, by running a server handling incoming requests. This can be useful when GIPSIE® is used within a Hardware in the Loop (HIL) setup. Run-time settings are applied via commands in the SCPI format. The following five categories, where parameters can be applied, are as follows (see also Scenario Simulation):

  1. Receiver
  2. Satellites
  3. Multipath
  4. Jammer
  5. Spoofer
  6. Spectrum-matched Jammer

# Definition of SCPI

In general, the Standard Commands for Programmable Instruments (SCPI) defines a standard for syntax and commands to use in controlling programmable test and measurement devices, such as automatic test equipment and electronic test equipment. There is a distinction between two types of commands:

  • SET: With this type of command, certain settings can be set at instrument site. For example SYSTem:COMMunicate:SERial:BAUD 2400 sets the baudrate of a RS232 interface to 2400 bits/s.
  • QUERY: With this type of command, certain information of a current instrument setting can be queried. For example SYSTem:COMMunicate:SERial:BAUD? gives the current set baudrate of the RS232 interface. Query operations always end with a question mark.

Some commands can both set and query an instrument at once (more information can be found at [1] and [2]).

# Definition of SCPI within GIPSIE

The sending and receiving of run-time settings in GIPSIE® is realized via a TCP/IP interface, where SCPI commands are utilized.

  1. A TCP client shall be able to send a request (SET), for example new run-time settings, as a SCPI command. The server will not send a response back.
  2. A TCP client shall be able to send a request (QUERY), for example the current status of the TCP server, as a SCPI command. Here the server will send back an appropriate response.

In order to simplify things, only short-notation commands are used. Requests are handled as follows:

  • For GIPSIE®, SET operations always send a <json> string to the server.
  • For every request, the client shall create a new connection.
  • The server shall parse a message if a defined <end-char> is found.
  • The server shall parse a message if the connection is closed.
  • Everything which is received after parsing a message shall be ignored.
  • In case the request was a QUERY, the server shall send back a response in the same connection tunnel.
  • In order to check if a SET operation was successful, an event queue can be read out, giving the current status caused by the latest request.

The run-time settings are split up to separate commands, depicting each category of setting SETS e.g. satellites, receivers, etc.

# Available SCPI commands

The following SET and QUERY operations can be send to the GIPSIE® TCP server:

NOTE

<json> defines the payload of a command.

NOTE

<end-char> is the character, which defines the end of the request. Currently, a newline character \n is defined to signalize the end of the payload.

# Available SETS

  1. Set new satellite run-time settings: GIPSIE:SETT:SAT <json> <end-char>
  2. Set new receiver run-time settings: GIPSIE:SETT:REC <json> <end-char>
  3. Set new jammer run-time settings: GIPSIE:SETT:JAM <json> <end-char>
  4. Set new spoofer run-time settings: GIPSIE:SETT:SPF <json> <end-char>
  5. Set new spectrum-jammer run-time settings: GIPSIE:SETT:SJ <json> <end-char>
  6. Set new multipath run-time settings: GIPSIE:SETT:MP <json> <end-char>

# Available QUERIES

  1. Query current status from event queue: GIPSIE:STAT? <end-char>
  2. Query current satellite run-time settings: GIPSIE:SETT:SAT? <end-char>
  3. Query current receiver run-time settings: GIPSIE:SETT:REC? <end-char>
  4. Query current jammer run-time settings: GIPSIE:SETT:JAM? <end-char>
  5. Query current spoofer run-time settings: GIPSIE:SETT:SPF? <end-char>
  6. Query current spectrum-jammer run-time settings: GIPSIE:SETT:SJ? <end-char>
  7. Query current multipath run-time settings: GIPSIE:SETT:MP? <end-char>

# Definition of run-time setting categories

The definitions are composed in the JSON format.

# Receiver State

# SET

Set receiver state:

GIPSIE:SETT:REC <json> <end-char>

JSON Payload as string:

{
    "id": 1,
    "state": {
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],  
        // local level (north [m/s], east [m/s], up [m/s])
        "velocity": [12.5, 11.4, 10.3],   
        // local level (north [m/s²], east [m/s²], up [m/s²])
        "acceleration": [1.6, 2.7, 3.8],
        // body frame attitude (roll [°], pitch [°], yaw [°])
        "attitude": [1.0, 0.0, 0.0],
        // body frame rate of attitude (roll [°/s], pitch [°/s], yaw [°/s])
        "attitude-dot": [-1.0, 0.0, 0.0],
    }
}

NOTE

Position, velocity and acceleration as well as roll, pitch and yaw are optional. The following notation is used:

  • x: position
  • v: velocity
  • a: acceleration
  • r: roll
  • p: pitch
  • y: yaw

The following combinations are possible:

Combinations
  • x:
  • x, v:
  • x, v, a:
  • x, a:
  • v:
  • v, a:
  • a:
  • r, p, y:
  • r-dot, p-dot, y-dot:
  • r, p, y and r-dot, p-dot, y-dot:

All parameters (except the id) are optional:

Name Type Optional
id integer no
state double array yes

# QUERY

Query last receiver state:

GIPSIE:SETT:REC? <end-char>

returns last receiver state set, i.e.:

{"STATUS": "applied", "COMMAND": {"id": 1, "state": {"acceleration": [0.0, 3.0, 0.0]}}}

# Satellite

# SET

Set satellite state:

GIPSIE:SETT:SAT <json> <end-char>

JSON Payload as string:

{
    "system": "SBAS",
    "satellites": [
        { 
            "prn": 120,
            "active": true,
            "healthy": false,
            "received-signal-power": -165.0
        }
    ]
}

NOTE

Multiple satellites for one system can be changed in one request

{ 
    "system": "GPS",
    "satellites": [
        { "prn": 1, "active": false, "received-signal-power": -170.0 },
        { "prn": 2, "active": true, "received-signal-power": -170.0 },
        { "prn": 3, "active": true, "received-signal-power": -170.0 },
        { "prn": 4, "active": true, "received-signal-power": -170.0 },
    ]
}

All parameters (except the prn) are optional, and it is possible to set more than one satellite per request:

Name Type Optional
prn integer no
active boolean yes
healthy boolean yes
received-signal-power double [dBW] yes

The active status can only be changed for satellites already active and actually simulated in the scenario.

# QUERY

Query last satellite commands:

GIPSIE:SETT:SAT? <end-char>

returns last satellites set command:

{"STATUS": "applied", "COMMAND": {"satellites": [{"active": false, "prn": 1}], "system": "GPS"}}

Allowed SBAS PRNs

See Current Status of SBAS satellites for more information. Use the flag SBAS for the following SBAS Systems:

SBAS Nat PRN
EGNOS EU 120, 121, 123, 124 (reserved), 126, 136
SDCM Russia 125, 140, 141
GAGAN India 127, 128, 132
MSAS Japan 129, 137
BDSBAS China 130, 143, 144
NSAS Nigeria 147
WAAS USA 131, 137

Allowed GNSS PRNs

GNSS PRN Example
GPS 1 - 32 {"satellites": [{"active": false, "prn": 24}], "system": "GPS"}
Galileo 1 - 50 {"satellites": [{"active": false, "prn": 2}], "system": "GALILEO"}
GLONASS 1 - 63 {"satellites": [{"active": false, "prn": 12}], "system": "GLONASS"}
SBAS 120 - 158 {"satellites": [{"active": false, "prn": 120}], "system": "SBAS"}
QZSS 193 - 202 {"satellites": [{"active": false, "prn": 193}], "system": "QZSS"}
BeiDou 1 - 63 {"satellites": [{"active": false, "prn": 1}], "system": "BEIDOU"}
NavIC (IRNSS) 1 - 14 {"satellites": [{"active": false, "prn": 1}], "system": "IRNSS"}

# Jammer

# SET

Set jammer state:

GIPSIE:SETT:JAM <json> <end-char>

JSON Payload as string:

{
    "id": 1,
    "active": true,
    "power": -130,  // absolute power in dBW
    "state": {
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],
        // local level (north [m], east [m], up [m])
        "velocity": [12.5, 11.4, 10.3],
        // local level (north [m], east [m], up [m])
        "acceleration": [1.6, 2.7, 3.8]
    }
}

All parameters (except the id) are optional:

Name Type Optional
id integer no
active boolean yes
power double [dBW] yes
state double array yes

# QUERY

Query last jammer state:

GIPSIE:SETT:JAM? <end-char>

returns last jammer state set, i.e.:

{"STATUS": "applied", "COMMAND": {"active": true, "id": 1, "power": -130}}

# Spoofer

# SET

Set spoofer state:

GIPSIE:SETT:SPF <json> <end-char>

JSON Payload as string:

{
    "id": 1,
    "active": true,
    // relative power (to authentic signals) in dB
    "power": 5, 
    // spoofer state
    "state-spoofer": {                              
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],
        // local level (north [m], east [m], up [m])
        "velocity": [12.5, 11.4, 10.3],
        // local level (north [m], east [m], up [m])
        "acceleration": [1.6, 2.7, 3.8]
    },
    // the state, which the spoofer assumes its target (victim) has
    "state-target": {                           
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],
        // local level (north [m], east [m], up [m])
        "velocity": [12.5, 11.4, 10.3],
        // local level (north [m], east [m], up [m])
        "acceleration": [1.6, 2.7, 3.8]
    },
    // the state, which the spoofer forces on the overtaken receiver
    "state-sim-rec": {                          
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],
        // local level (north [m], east [m], up [m])
        "velocity": [12.5, 11.4, 10.3],
        // local level (north [m], east [m], up [m])
        "acceleration": [1.6, 2.7, 3.8]
    }
}

All parameters (except the id) are optional:

Name Type Optional
id integer no
active true or false yes
power double, [dB] yes
state-spoofer double array yes
state-target double array yes
state-sim-rec double array yes

# QUERY

Query last spoofer state:

GIPSIE:SETT:SPF? <end-char>

returns last spoofer state set, i.e.:

{"STATUS": "applied", "COMMAND": {"active": true, "id": 1, "power": 5, "state-sim-rec": {"position": [47.1, 15.1, 500.0]}}}}

# Spectrum-matched Jammer

# SET

Set spectrum-jammer state:

GIPSIE:SETT:SJ <json> <end-char>

JSON Payload as string:

{
    "id": 1,
    "active": true,
    // relative power (to authentic signals) in dB
    "power": 5, 
    // spectrum-jammer state
    "state-sj": {                              
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],
        // local level (north [m], east [m], up [m])
        "velocity": [12.5, 11.4, 10.3],
        // local level (north [m], east [m], up [m])
        "acceleration": [1.6, 2.7, 3.8]
    },
    // the state, which the spectrum-jammer assumes its target (victim) has
    "state-target": {                           
        // ellipsoidal WGS-84 (lat [deg], lon [deg], h [m])
        "position": [47.1, 15.1, 350.0],
        // local level (north [m], east [m], up [m])
        "velocity": [12.5, 11.4, 10.3],
        // local level (north [m], east [m], up [m])
        "acceleration": [1.6, 2.7, 3.8]
    }
}

# QUERY

Query last spectrum-jammer state:

GIPSIE:SETT:SJ? <end-char>

returns last spectrum-jammer state set, i.e.:

{"STATUS": "applied", "COMMAND": {"active": true, "id": 1, "power": 5, "state-sj": {"position": [47.1, 15.1, 500.0]}}}}

# Multipath

# SET

Set multipath settings:

GIPSIE:SETT:MP <json> <end-char>

JSON Payload as string:

{"id": 1, "active": true, "mask": "tunnel"}
{"id": 1, "active": false, "mask": "none"}
Name Type Optional Note
id integer no has to be a valid receiver id; otherwise the runtime setting is ignored as a whole
active boolean no activates / deactivates multipath
mask string no sets the mask identified by the string given; has to be part of the scenario; if the name is not found, the runtime setting is ignored as a whole

# QUERY

Query last spoofer state:

GIPSIE:SETT:MP? <end-char>

returns last multipath settings set, i.e.:

{"STATUS": "applied", "COMMAND": {"active": true, "id": 1, "mask": "obstruction"}}

# Test with UNIX command line tools

Send new receiver state to client via netcat nc:

echo -ne 'GIPSIE:SETT:REC {"id": 1, "active": true, "state": {"position": [47.1, 15.1, 350.0], "velocity": [12.5, 11.4, 10.3], "acceleration": [1.6, 2.7, 3.8]}} \n' | nc localhost 8080

Query current status:

echo -ne 'GIPSIE:SETT:REC? \n' | nc localhost 8080

  1. https://www.ivifoundation.org/docs/SCPI-99.PDF ↩︎

  2. https://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments ↩︎

←