Skip to main content

ProGlove Documentation

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)