Scan event

Scan event is an event message that notifies about a scan from a connected scanner.

Fields

Name	Type	Description	Accepted values	Constraints	Required
`api_version`	string	The API version in which this request is valid.	`1.0`		Yes
`event_type`	string	The message type.	`scan`		Yes
`event_id`	string	The message identifier (UUID) of the event.	Example: `“02114da8-feae-46e3-8b00-a3f7ea8672df"`	UUID format `[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`	Yes
`time_created`	integer	The UNIX timestamp in milliseconds when the message was created.	`1546300800000`	1546300800000 <= value <= 99999999999999	Yes
`scan_code`	string	The scanned data when the message is of type 'scan' (excluding bytes that are invalid characters).	UTF-8	1 <= length <= 2000	Yes
`scan_bytes`	string	The scanned data when the message is of type 'scan' encoded in URL-safe Base64 (useful when scanning bytes that are no valid UTF-8).	Any	1 <= length <= 2000	No
`device_serial`	string	The serial number of the scanner for which the command is intended.	Any	1 <= length <= 128	Yes
`device_model`	string	The model of the scanner.	LEO, MARK Basic, MARK 2, MARK 3, MARK Display	Only the accepted values are valid.	Yes
`gateway_serial`	string	The serial number of the Gateway Plus that will receive the command.	Any	1 <= length <= 128	Yes
`scan_mode`	string	The type of scan performed.	`SCAN_MODE_SINGLE`, `SCAN_MODE_CONTINUOUS`, `SCAN_MODE_MULTISCAN`	Only the accepted values are valid.	No
`scan_duration`	float	The time it takes to scan the barcode (from triggering to capturing the scanned content).	Any	value >= 0.0	No
`device_temperature`	float	The temperature of the scanner.	Any	value >= 0.0	No
`scan_session_id`	integer	The current scanning session ID.	Any	value > 0	No

Example

{
  "api_version": "1.0",
  "event_type": "scan",
  "event_id": "02114da8-feae-46e3-8b00-a3f7ea8672df",
  "time_created": 1546300800000,
  "scan_code": "Hello, World!",
  "scan_bytes": "SGVsbG8sIFdvcmxkIQ==",
  "device_serial": "MDMR000000064",
  "device_model": "MARK Display",
  "gateway_serial": "PGGP000000058",
  "scan_mode": "SCAN_MODE_SINGLE",
  "scan_duration": "1.23",
  "device_temperature": "22.30",
  "scan_session_id": 1
}

Binary Scan Data

Streams API uses JSON as marshalling format and therefore any string in a message is implicitly UTF-8 encoded. But as some barcode symbologies allow for other character encoding such as binary strings we want to also represent data that is not UTf-8 encoded.

To allow the transport of arbitrary e.g. binary strings in Streams API scan event messages, the data is armored using Base64 encoding.

Base64 Encoding details

The data in scan_bytes is encoded using the URL-safe alphabet.

E.g. the following Python 3 code simulates the effect:

from base64 import urlsafe_b64encode as b64encode

original_data : bytes = get_scan_data_from_somewhere()
scan_message.scan_bytes = b64encode(original_data).decode()

Handling Binary Scan Data

To consume the binary scan data the Base64 encoding needs to be undone. E.g. in Python 3 this needs also conversion between UTF-8 encoded str strings as used by JSON and raw bytes:

from base64 import urlsafe_b64decode as b64decode
from typing import Any

def handle_scan_event(event: dict[str, Any]) -> bytes:
    """
    Handler to react to a scan stream event.
    """
    if "scan_bytes" not in event:
        return
    raw_bytes = b64decode(event["scan_bytes"].encode())
    do_something_with_the_data(raw_bytes)

In this section:

ProGlove Documentation