Acquisition Controller

Table of Contents

Overview

The acquisition controller is responsible for acquiring images from the cameras, configuring said cameras, synchronizing the receptions with some telemetry measurements, and writing all of that to disk. Most of the time, that is going to be a temporary location but managing that falls outside the responsibility of the acquisition controller. We are only concerned with getting images, saving them to disk, and lining up the images with a telemetry sample at this stage.

Hardware Interfaces

To acquire images, the acquisition controller needs cameras and a trigger controller. The cameras can be connected via USB, ethernet, and really any number of physical interfaces, as long as a driver is coded for it. The trigger controller is known everywhere as the SMC. This SMC is connected via serial USB.

Control Interfaces

Overview

Control over the acquisition controller is possible via a REST style API. An HTTP request handler is built into the acquisition controller and serves a few paths to allow limited control over the devices and visibility into the state of the system. In the first implementation, the HTTP handler listens on port 34568 for incoming requests.

This interface allows the user to start and stop the capture of images, but also to set some camera properties and activate some features of specific cameras.

Endpoints

GET /control

This endpoint serves a very simple HTML page that allows you to drive the other endpoints of this service. This is only intended as a testing facility.

GET /control/start

This endpoint will start recording images. Query arguments are used to determine where the image files shall be saved and how to name them.

Query parameters:

  • location

    • Type: string
    • Description: Absolute path where the images are to be saved
    • Optional: yes

  • prefix

    • Type: string
    • Description: text that shall be prepended to the image names when saving.
    • Optional: yes

Notes: If the location and prefix are empty, the images will be saved next to the executable location. If the prefix is present, the images will be named as follows: prefix_<cam_name>_<count>.<extension> where cam_name and extension is extracted from the XML configuration file, and count is an auto-incrementing number that will ensure each name is unique.

GET /control/stop

This endpoint will suspend the recording of images.

GET /control/telemetry

The route will return a JSON blob containing the latest telemetry report received from the SMC.

GET /control/list_cameras/{camera_name}

The route will return a JSON blob containing the list of cameras loaded by the acquisition controller and their parameters with values.

Path parameters:

  • camera_name
    • Type: string
    • Description: name of the camera, as defined in the XML configuration file.
    • Optional: yes

Query parameters:

  • includeSmc
    • Type: bool
    • Description: dictates if the SMC should be listed with the other sensors present.
    • Optional: yes

Return value: 

[
    {
        "model": "",
        "name": "",
        "serial": "",
        "spectrum": "",
        "status": {
            "message": "",
            "state": "normal", "degraded" or "error"
        }
    },
    {
     
    }
]

GET /control/{camera_designation}/list_parameters

Each camera has different capabilities and different parameters that can be set and queried. They are defined in the XML configuration file. This method will list out those parameters

Path parameters:

  • camera_designation
    • Type: string or int
    • Description: name of the camera, as defined in the XML configuration file. Or index of the camera in the array held in the acquisition controller. There is no guarantee regarding the ordering in said array.
    • Optional: no
Additional Information

There are a few parameters accessible to control the performance of the camera drivers.

  • Scale
    • Description: ratio by which to scale the native image. A value less than 1 will reduce the size of the image and speedup the compression and transfer when getting the image.
    • Type: float
  • Quality
    • Description: Value between 0 (worst quality) and 100 (almost lossless) indicating the amount of compression to apply on the image when converting to webp.
    • Type: integer

GET,POST /control/{camera_designation}/set

A few parameters can be changed at runtime. Those parameters can vary for each camera. This endpoint allows the caller to assign a new value to different runtime parameters.

Path parameters:

  • camera_designation
    • Type: string or int
    • Description: name of the camera, as defined in the XML configuration file. Or index of the camera in the array held in the acquisition controller. There is no guarantee regarding the ordering in said array.
    • Optional: no

Query parameters:

  • <parameter_name>
    • Type: bool, float, int
    • Description: This is the name of the parameter for which we want to set a value. This name should appear in the XML configuration file and the value assigned must be of the same type as what is declared in the XML. There can be any number of parameters declared in the query.
    • Optional: yes

Request body: The list of parameters to set can also extend to the body, as a JSON object following the format:

{
  "<param_name1>": value,
  "<param_name2>": value,
  ...

  "<param_nameN>": value
}

The parameters set in the query and in the body will be merged to a single list all applied to the camera.

GET /control/{camera_designation}/execute/{command_name}

Some cameras, namely the IR cameras, have commands that can be executed. Good example of this is the non-uniformity correction of the FLIR. This endpoint allows the execution of some commands on some cameras. The commands can be found in the list of parameters returned by the list command

Path parameters:

  • camera_designation

    • Type: string or int
    • Description: name of the camera, as defined in the XML configuration file. Or index of the camera in the array held in the acquisition controller. There is no guarantee regarding the ordering in said array.
    • Optional: no

  • command_name

    • Type: string
    • Description: name of the command to execute, as defined in the XML file.
    • Optional: no

GET /control/{camera_designation}/query/{parameter_name}

Retrieve the current value of a parameter.

Path parameters:

  • camera_designation

    • Type: string or int
    • Description: name of the camera, as defined in the XML configuration file. Or index of the camera in the array held in the acquisition controller. There is no guarantee regarding the ordering in said array.
    • Optional: no

  • parameter_name

    • Type: string
    • Description: name of the parameter to query, as defined in the XML file.
    • Optional: no

GET /control/{camera_designation}/image

Retrieve the latest image acquired by the designated camera. Image returned will be in the webp format. Scale and compression ratio of the image are controllable using the .../set route.

Path parameters:

  • camera_designation
    • Type: string or int
    • Description: name of the camera, as defined in the XML configuration file. Or index of the camera in the array held in the acquisition controller. There is no guarantee regarding the ordering in said array.
    • Optional: no

GET/POST /control/environment

Post to update, get to read, environmental readings. At this time, the only source for those values is the UI so the get will be empty until a post is made. Until a more automated source of data can be integrated, the full control and responsibility of this data lies with the UI.

Query parameters:

  • *
    • Type: double
    • Description: any query parameter is added to the map of values that will be dumped to the metadata package when an image is captured.
    • Optional: no

GET /control/gps

Endpoint to write new GPS antenna offsets in the INS. This route will forward the x, y, z offsets to the SMC and eventually to the INS where they will be written to flash and persist after power cycles. The endpoint will also cause the INS to be reset, which is necessary for the offsets to be applied to the filter. Offsets are to be measured in meters. The coordinate frame follows the right hand rule with x pointing out of the lens, y pointing towards the back of the plane when the rig is looking out the right side window, and z pointing towards the ground.

Query parameters:

  • x
    • Type: double
    • Description: offset in the x axis
  • y
    • Type: double
    • Description: offset in the y axis
  • z
    • Type: double
    • Description: offset in the z axis

GET /control/disk_space

Endpoint to query the remaining disk space available in the currently selected save location.

Return value:

{
  "path": "path",
  "capacity": capacity in bytes
  "free":  free in bytes
  "available": available in bytes
  "available_gb":  available in gigabytes
}

GET /control/set_rate

Set the SMC trigger rate for some device. The device names are strings configured in the firmware of the SMC.

Query parameters:

  • ident:
    • Type: string
    • Description: name of the device who's rate is to be set
  • rate:
    • Type: double
    • Description: rate of trigger in hertz

GET /control/status

Endpoint to get the status of the capture recording.

Return value: 

{
  "capture_running": boolean
}

Data Publishing Interfaces

Telemetry information, along with the corresponding image file association information, is also recorded as files, specifically JSON files. Those files are stored in the same directory next to the image files.

Telemetry

For use of this telemetry data outside the acquisition controller, the same content is also published on a ZMQ socket. Port 5556 is used for this publisher and the content published on this socket is defined by the protobuf structure located in this repository Specifically, the AcquisitionControllerMessage is generated and serialized before being published. This message contains all the telemetry information received by the controller. It is published for every telemetry sample received, so at a much higher rate than the incoming images, a field in the message indicates if this frame aligns with some images.

Files

A second ZMQ publisher running on port 5550 publishes the file synchronization information. The content of this publisher follows the ImageMatch structure defined in this repository. It essentially associates a series of files with a telemetry identifier. This message is published once when a new synchronization match is established.