MAPS websocket interface

MAPS devices can be operated in a mode where the device is returning data and can be controller over websocket connection.

In websocket mode, the user can connect to the device with any application over using the websocket protocol. The device is by default listening for connection on port 9002, but port number can vary in devices. Please refer to the information card supplied with your devices for more specific information.

Upon connection the device communicates by sending and receiving data and commands in a json format. For example:

{
    type: "output",
    msg: "position",
    data: "[00001024], ...",
    time: "07/12/2023 14:20:15.123456"
}

The above example shows a position output of the MAPS device.

Message structure

The messages have some common and variable fields. Most common fields are:

• type: Type of the message. Value is usually , "output" or "info".
  • "control" messages denote commands that influence the operation of the device or messages that indicate information about the status of the device.
  • "output" type messages contain intended output of the device, i.e., some variant of position information.
  • "info" type messages hold some kind of information about the device, or a notification for an event that happened.
• "command" is the command of sent to the device in case the control message contains one.
• "msg" is the usually the message itself, or some kind of further information about the content of the message.
• "data" is a larges chink of embedded data, in case the message. In the example it is the position data from the device.
• "time" is the timestamp of the sender at the exact time of sending the message. Time information is in a [day]/[month]/[year] [hour]:[min]:[sec].[microsec] format.
• "pre" is the corresponding previous message, in case the current message is a response to a previous one from the other peer.

Messages

In this section we will supply a list of most common messages that the MAPS device can receive and send.

Device output

By default, the device provides output in the following structure:

{
    type: 'output',
    msg: 'position',
    data: '[index], X, Y, Z, aX, aY, aZ, "good"/"bad", "*****", capture_timestamp, sensore_timestamp, monotonic_timestamp',
    time: 'day/mo/year hh:mm:ss.usec'
}

According to the operation mode of the device, output results can arrive automatically, or on demand as a response to a request.

Control messages

Control messages are the commands that the connected application can send to the device for ordering it to perform specific operations. The usable control messages and the corresponding responses of the device are listed below.

ping

The ping message is intended to test if the application is online and responsive.

{
    type: "control",
    command: "ping"
}

Response:

{
    type: "control",
    msg: "ack",
    pre: "ping",
    time: "day/mo/year hh:mm:ss.usec"
}

strobe

The strobe message commands the device to make a capture and calculate position data. As calculation of position data might take a longer period of time, the device responds with an ack message and results can be obtained by the datarx message.

{
    type: "control",
    command: "strobe"
}

response:

{
    type: "info",
    msg: "ack",
    pre: "strobe",
    time: "day/mo/year hh:mm:ss.usec"
}

datarx

After receiving the datarx command the device sends the latest position information back. One should not, that the same position information might be queried multiple times.

{
    type: "control",
    command: "datarx"
}

response:

{
    type: "output",
    msg: "position",
    pre: "datarx",
    time: "day/mo/year hh:mm:ss.usec"
    data: '[index], X, Y, Z, aX, aY, aZ, "good"/"bad", "*****", capture_timestamp, sensore_timestamp, monotonic_timestamp',
}

calibrate

For improving the performance of the MAPS device, the camera sensor needs calibration periodically. This is especially important if lighting condition on the scale changes.

{
    type: "control",
    command: "calibrate"
}

response:

{
    type: "info",
    msg: "ack",
    pre: "calibrate",
    time: "day/mo/year hh:mm:ss.usec"
}

setcapturemode

The MAPS device has multiple capture modes, that can be set via the setcapturemode command. The mode filed is the integer index of the desired mode. For further information see MAPS control modes.

{
    type: "control",
    command: "setcapturemode"
    mode: [int]
}

response:

{
    type: "info",
    msg: "ack",
    pre: "setcapturemode",
    time: "day/mo/year hh:mm:ss.usec"
}

hwpulse

The sensor of the MAPS device can operate in different modes, one of which includes being triggered by an electrical pulse. The MAPS device itself is also capable of emitting such a trigger pulse in cases one tries to synchronize the capture of multiple sensors.

{
    type: "control",
    command: "hwpulse"
}

response:

{
    type: "info",
    msg: "ack",
    pre: "setcapturemode",
    time: "day/mo/year hh:mm:ss.usec"
}

paramrx

The device has multiple internal parameters that can be requested on the websocket connections. Detailed description of the parameters are supplied to partners in a separate document.

{
    type: "control",
    command: "paramrx"
}

response:

{
    type: "info",
    msg: "ack",
    pre: "paramrx",
    time: "day/mo/year hh:mm:ss.usec"
    data: {
        app: ...
        scale: ...
        sensor: ...
        algo: ...
    }
}

logout

The logout message initiates termination of the websocket connection. After responding to this message the device will close current connection. Note, that the client can also simply be terminated at client side.

{
    type: "control",
    command: "logout"
}

response:

{
    type: "info",
    msg: "ack",
    pre: "logout",
    time: "day/mo/year hh:mm:ss.usec"
}