Emulator APIs

Each bitstream emulator will have a number of API routes defined in individual IP block emulators, as well as a number of standardized routes across all emulators.

If running via minikube/k8s, the hostname for each bitstream emulator is

<bitstream_emulator_id>.<namespace>.svc.cluster.local:5001

which can be accessed via any pod in the cluster, e.g.

curl -v fhs-vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/ethernet_200g/status

Otherwise, for Docker, it is http://emulator:5001 (preferred by Docker) or http://localhost:5001 and is only accessible from within the same container as the running emulator.

Standardized Routes

Controller API

Each bitstream emulator has the following top-level API routes:

Stop

POST /stop

Stop the emulator, but do not shutdown the API server. Useful to temporarily stop generating logs. Will allow the most recent pulse to finish flowing through the system.

Example request:

curl -v -X POST vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/stop
Status Codes:

  • 202 Accepted – Request to stop has been accepted and should complete shortly.

  • 409 Conflict – The emulator is not currently in a state in which it is allowed to stop.

Start

POST /start

Start the emulator from a stopped state.

Example request:

curl -v -X POST vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/start
Status Codes:

  • 202 Accepted – Request to start has been accepted and should complete shortly.

  • 409 Conflict – The emulator is not currently in a state in which it is allowed to start.

Terminate

POST /terminate

Terminate/teardown the emulator entirely. Will gracefully end all subscriptions and then tear down the API server, ending the script (note that it may take a few seconds for all subscriptions to finish). If running in a pod, can be used to force a restart.

Example request:

curl -v -X POST vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/terminate
Status Codes:

  • 202 Accepted – Request to terminate has been accepted and should complete shortly.

  • 409 Conflict – The emulator is not currently in a state in which it is allowed to terminate.

State

GET /state

Get the current state of the emulator controller. This does not necessarily represent the state of any underlying IP block emulators.

Example request:

curl -v vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/state

Example response:

{
  "current_state": "IDLE"
}
Response JSON Object:

  • current_state (string) – the current state of the emulator controller.

Response Headers:
Status Codes:

  • 200 OK – Retrieved successfully.

Config

GET /config

Get the contents of the config.json file being used by the bitstream emulator. Useful to verify that the correct configuration was loaded when debugging/testing.

Example request:

curl -v vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/config

Example response:

{
  "id": "vcc",
  "version": "0.0.1",
  "ip_blocks": [
    {
      "id": "ethernet_200g",
      "display_name": "200Gb Ethernet MAC",
      "type": "ethernet_200g_r4",
      "downstream_block_ids": [],
      "constants": {
        "num_fibres": 4,
        "num_lanes": 4
      }
    }
  ],
  "first": ["ethernet_200g"]
}
Response Headers:
Status Codes:

  • 200 OK – Retrieved successfully.

Initial Signal

GET /initial_signals

Get the contents of the initial_signals_config.json file that was used to instantiate the bitstream emulator. Useful to verify that the correct initial signals were loaded when debugging/testing.

Example request:

curl -v vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/initial_signals

Example response:

{
  "initial_signals": [
    {
      "destination": "ethernet_200g",
      "signals": [
        {
          "tag": "default",
          "value": {
            "packet_rate": 1500000,
            "sample_rate": 3960000000,
            "dish_id": "MKT001",
            "band_id": "1",
            "regular_sky_power": [0.4, 0.5],
            "noise_diode_on_power": [0.5, 0.6],
            "duty_cycle": 0.50
          }
        }
      ]
    }
  ]
}
Response Headers:
Status Codes:

  • 200 OK – Retrieved successfully.

Server Healthcheck

GET /server_healthcheck

Get True if the API server is running and the emulator controller is not in an error state. Used to determine the health state of a pod.

Example request:

curl -v vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/server_healthcheck

Example response:

{}
Response Headers:
Status Codes:

Graph

GET /graph

Get a PNG image of a graph defined by the currently loaded config file, representing all of the connections between IP blocks.

Example request:

curl -v -o test_graph.png vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/graph

Example response:

HTTP/1.1 200 OK
Content-Type: image/png
Response Headers:
Status Codes:

  • 200 OK – Retrieved successfully.

IP Block Emulator API

Each IP block emulator also has the following standard API routes (in addition to their individual API implementations):

State

GET /(string: ip_block_id)/state

Get the current state of the IP block emulator. States will vary between blocks depending on their implementations.

Example request:

curl -v vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/ethernet_200g/state

Example response:

{
  "current_state": "RESET"
}
Parameters:

  • ip_block_id (string) – the IP block emulator ID to send the request to.

Response JSON Object:

  • current_state (string) – the current state of the specified IP block emulator.

Response Headers:
Status Codes:

  • 200 OK – Retrieved successfully.

State Diagram

GET /(string: ip_block_id)/state_diagram

Get a PNG image of a state-transition diagram representing the state machine of the IP block emulator, including the current/previous state.

Example request:

curl -v -o test_diagram.png vcc-emulator-1.ska-mid-cbf-emulators.svc.cluster.local:5001/ethernet_200g/state_diagram

Example response:

HTTP/1.1 200 OK
Content-Type: image/png
Parameters:

  • ip_block_id (string) – the IP block emulator ID to send the request to.

Query Parameters:

  • contextOnly (boolean) – Generate only a small section of the state machine representing the current state, previous state, and currently available transitions.

Response Headers:
Status Codes:

  • 200 OK – Retrieved successfully.