asyncapi: 2.6.0
info:
title: Datalogic Fixed Retail Scanner - Event API
version: "1.0"
# description: "Real time events from 9600i/9900i Fixed Retail Scanners"
# language=markdown
description: |
# FOR INTERNAL REVIEW ONLY #
The Datalogic Fixed Retail Scanner Event API allows third party clients to:
- Receive updates on mode/state changes
- Receive notification on Scanner System Events:
- Label Reads
- Scale Steady Weight/Weight Change/Zero
- Scale Sentry Beam Block/Unblocked
- Object Seen/Leaving Field of View
This API should be used alongside the Magellan 9900i/9600i SDK REST API to:
- Retrieve captured images
- Start/stop video streaming
- Read information and statistics
For details of the REST API, see the `Magellan 9900i/9600i SDK REST API`.
The REST is available from the scanner at `https://datalogic-base-SERIAL_NUMBER.local`.
termsOfService: https://someurl.com/terms
contact:
name: Fixed Retail Scanner Software Support
email: some_address@datalogic.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
websockets_server:
url: datalogic-base-serialNumber.local:433
protocol: wss
protocolVersion: "13"
description: Private 9600i/9900i WebSocket Server
channels:
/:
# language=markdown
description: |
Channel for all Events
Note: All paths after the port number are ignored
e.g. datalogic-base-serialNumber.local:433/ equivalent to datalogic-base-serialNumber.local:433/ws
subscribe:
description: Messages sent from Scanner
operationId: onScannerEvent
message:
oneOf:
- $ref: "#/components/messages/welcomeMsg"
- $ref: "#/components/messages/pongMsg"
- $ref: "#/components/messages/scannerModeStateMsg"
- $ref: "#/components/messages/scannerSystemLabelReadMsg"
- $ref: "#/components/messages/scannerSystemScaleMsg"
- $ref: "#/components/messages/scannerSystemScaleSentryMsg"
- $ref: "#/components/messages/scannerSystemObjectDetectMsg"
publish:
description: Messages sent to Scanner
operationId: sendMessageToScanner
message:
oneOf:
- $ref: "#/components/messages/pingMsg"
components:
messages:
welcomeMsg:
contentType: application/json
description: Welcome message sent to client on new connection
payload:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- welcomeMsg
data:
type: object
required:
- eventId
- connectionId
- apiVersionStr
- applicationVersionStr
- serialNumber
- buildVersion
properties:
eventId:
$ref: "#/components/schemas/eventId"
connectionId:
$ref: "#/components/schemas/connectionId"
apiVersionStr:
$ref: "#/components/schemas/apiVersionStr"
applicationVersionStr:
$ref: "#/components/schemas/applicationVersionStr"
serialNumber:
$ref: "#/components/schemas/serialNumber"
buildVersion:
$ref: "#/components/schemas/buildVersion"
examples:
- type: welcomeMsg
data:
eventId: "0123450"
connectionId: "1278248556"
apiVersionStr: "1.0"
applicationVersionStr: "DR941630"
serialNumber: "G23HBCXKE"
buildVersion: "9698e41a5b"
pingMsg:
contentType: application/json
description: Application level ping by client, server will respond back with a pong message
payload:
$ref: "#/components/schemas/pingMsg"
x-response:
$ref: "#/components/messages/pongMsg"
pongMsg:
contentType: application/json
description: Server response to ping message
payload:
$ref: "#/components/schemas/pongMsg"
scannerModeStateMsg:
contentType: application/json
# language=markdown
description: Indicates the mode or state of the scanner has changed
payload:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- scannerModeStateMsg
data:
type: object
required:
- eventId
- currentMode
- currentState
properties:
eventId:
$ref: "#/components/schemas/eventId"
currentMode:
type: string
# language=markdown
description: |
The mode the scanner is currently operating in
# sys_mode_t
enum:
- PRE_OPERATING # SYS_PREOPERATING_MODE
- LIMITED_SCANNING # SYS_LIMITED_SCANNING_MODE
- ACTIVE # SYS_ACTIVE_MODE
- PROGRAMMING # SYS_PROGRAMMING_MODE
- FRU_ISOLATION # SYS_FRU_ISOLATION_MODE
- ERROR # SYS_ERROR_MODE
- DIAGNOSTICS # SYS_DIAGNOSTICS_MODE
- SCALE_DIAGNOSTICS # SYS_SCALE_DIAG_MODE
- SCALE_CALIBRATION # SYS_SCALE_CALIBRATION_MODE
- ORT # SYS_ORT_MODE
examples:
- ACTIVE
currentState:
type: string
# language=markdown
description: |
The corresponding state for 'currentMode'
# sys_state_t
enum:
- IDLE # SYS_IDLE_STATE
- SCANNING_DISABLED # SYS_SCANNING_DISABLED_STATE
- SCANNING_ENABLED # SYS_SCANNING_ENABLED_STATE
- SLEEP # SYS_SLEEP_STATE
- SLUMBER # SYS_SLUMBER_STATE
examples:
- SCANNING_ENABLED
examples:
- type: scannerModeStateMsg
data:
eventId: "0123450"
currentMode: ACTIVE
currentState: SCANNING_ENABLED
scannerSystemLabelReadMsg:
# language=markdown
description: |
Indicates a label has been read
Note: The following labels won't be sent to clients:
- Any special purpose label read by the scanner
- Any scanner programming label
- Any label whose source is from an attached USB barcode reader
- Any special purpose label generated by the scanner
contentType: application/json
payload:
type: object
properties:
type:
type: string
description: Type of message
enum:
- scannerSystemLabelReadMsg
data:
type: object
required:
- eventId
- labelIdType
- labelSubType
- aimID
- labelSource
- labelData
properties:
eventId:
$ref: "#/components/schemas/eventId"
labelIdType:
type: string
# language=markdown
description: |
The label type
Note: `INVALID_LABEL_TYPE` indicates the type could not be determined
enum:
- ABC_CODABAR
- ANKER_PLESSEY
- AZTEC
- BC412
- C128_ADDON
- C128_PROGRAMMING_LABEL
- CAPTURE_IMAGE_LABEL
- CC_A
- CC_B
- CC_C
- CODABAR
- CODABLOCK_A
- CODABLOCK_F
- CODE11
- CODE128
- CODE16K
- CODE32
- CODE39
- CODE39_CIP
- CODE39_DANISH_PPT
- CODE39_LAPOSTE
- CODE39_PZN
- CODE4
- CODE49
- CODE5
- CODE93
- COMPRESSED_2OF5
- DATABAR_14
- DATABAR_14_COMPOSITE
- DATABAR_EXPANDED
- DATABAR_EXPANDED_COMPOSITE
- DATABAR_LIMITED
- DATABAR_LIMITED_COMPOSITE
- DATALOGIC_2OF5
- DATAMATRIX
- DATAMATRIX_PROGRAMMING_LABEL
- DIGIMARC_NATIVE
- DOTCODE
- EAN128
- EAN128_COMPOSITE
- EAN13
- EAN13_COMPOSITE
- EAN13_P2
- EAN13_P5
- EAN13_P8
- EAN8
- EAN8_COMPOSITE
- EAN8_P2
- EAN8_P5
- EAN8_P8
- FNC3_C128_LABEL
- FOLLETT_2OF5
- GENERIC_DATA
- GS1_DATAMATRIX
- GS1_DIGITAL_LINK_LABEL_SET_ID
- GS1_QR_CODE
- GTIN
- GTIN_P2
- GTIN_P5
- GTIN_P8
- HAN_XIN_CODE
- IATA_INDUSTRIAL_2OF5
- INDUSTRIAL_2OF5
- INTERLEAVED_2OF5
- INTERLEAVED_2OF5_CIP_HR
- ISBN
- ISBT128
- ISSN
- LABELIMAGE
- MATRIX_2OF5
- MAXICODE
- MICRO_PDF
- MICROQR
- MSI
- NW7_CODABAR
- OCR_A
- OCR_B
- OCR_MICR
- PDF417
- PHARMACODE_ONE_TRACK
- PHARMACODE_TWO_TRACK
- PLESSEY
- POSTAL_AUSTRALIAN
- POSTAL_IMB
- POSTAL_JAPANESE
- POSTAL_KIX
- POSTAL_PLANET
- POSTAL_PORTUGAL
- POSTAL_ROYAL_MAIL
- POSTAL_SWEDISH
- POSTNET
- QR_CODE
- STANDARD_2OF5
- TIMER_EXPIRED_EVENT
- TLC39
- TRIOPTIC
- TWO_LABEL_PAIR
- UPC2
- UPC5
- UPCA
- UPCA_COMPOSITE
- UPCA_P2
- UPCA_P5
- UPCA_P8
- UPCE
- UPCE_COMPOSITE
- UPCE_P2
- UPCE_P5
- UPCE_P8
- INVALID_LABEL_TYPE # Could not determine label type
labelSubType:
description: May contain addition data about the label type
type: string
examples:
- ""
aimID:
# language=markdown
description: |
The standard 3 character ISO/IEC label identifier.
For possible values, see the ISO/IEC 15424 specification.
Labels without a defined value are reported as `]X0`
type: string
minLength: 3
maxLength: 3
examples:
- "]E0"
- "]X0"
labelSource:
# language=markdown
description: |
The source of the scanned label
- `horizontal`: The horizontal plane (below the platter) on the base barcode scanner
- `vertical`: The vertical plane (in the bonnet) on the base barcode scanner
- `tdr`: The Top Down Reader (TDR)
- `cfr`: The Customer Facing Reader (CFR) attached to the TDR
- `stitched`: The label was a result of stitching multiple pieces together.
- The pieces may have been from multiple source so the "true source" is unknown.
type: string
enum:
- horizontal
- vertical
- tdr
- cfr
- stitched
examples:
- horizontal
labelData:
type: string
# language=markdown
description: |
The label data
examples:
- "123456789012"
examples:
- type: scannerSystemLabelReadMsg
data:
eventId: "0123451"
labelIdType: "UPCA"
labelSubType: ""
aimID: "]E0"
labelSource: "horizontal"
labelData: "123456789012"
scannerSystemScaleMsg:
contentType: application/json
payload:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- scannerSystemScaleMsg
data:
type: object
required:
- eventId
- scaleEventType
- scaleWeight
- scaleUnits
properties:
eventId:
$ref: "#/components/schemas/eventId"
scaleEventType:
type: string
# language=markdown
description: |
The type of scale event. This is only sent when using the internal scale.
- `STEADY_WEIGHT`: Scale is at a steady weight
- `ZERO_WEIGHT`: Scale is at center of zero (0.00)
- `STEADY_WEIGHT_CHANGED`: Weight is steady but has changed from the prior steady weight
without going to steady zero before.
enum:
- STEADY_WEIGHT # SYS_EVENT_STEADY_WEIGHT
- ZERO_WEIGHT # SYS_EVENT_ZERO_WEIGHT
- STEADY_WEIGHT_CHANGED # SYS_EVENT_STEADY_WEIGHT_CHANGED
examples:
- STEADY_WEIGHT
scaleWeight:
type: string
# language=markdown
description: |
The weight on the scale.
examples:
- "1.23"
scaleUnits:
type: string
# language=markdown
description: |
`scaleWeight` units
enum:
- lb
- kg
examples:
- lb
examples:
- type: scannerSystemScaleMsg
data:
eventId: "0123452"
scaleEventType: "STEADY_WEIGHT"
scaleWeight: "0.50"
scaleUnits: "lb"
scannerSystemScaleSentryMsg:
contentType: application/json
payload:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- scannerSystemScaleSentryMsg
data:
type: object
required:
- eventId
- scaleSentryEventType
properties:
eventId:
$ref: "#/components/schemas/eventId"
scaleSentryEventType:
type: string
# language=markdown
description: |
The type of Scale Sentry event
enum:
- BEAM_BLOCKED # SYS_EVENT_SCALE_SENTRY_BEAM_BLOCKED
- BEAM_UNBLOCKED # SYS_EVENT_SCALE_SENTRY_BEAM_UNBLOCKED
examples:
- BEAM_BLOCKED
examples:
- type: scannerSystemScaleSentryMsg
data:
eventId: "0123453"
scaleSentryEventType: BEAM_BLOCKED
scannerSystemObjectDetectMsg:
contentType: application/json
payload:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- scannerSystemObjectDetectMsg
data:
type: object
required:
- eventId
- objectDetectEventType
properties:
eventId:
$ref: "#/components/schemas/eventId"
objectDetectEventType:
type: string
# language=markdown
description: |
The type of Object Sense event
enum:
- OBJECT_SEEN # SYS_EVENT_OBJECT_SEEN
- OBJECT_NOT_SEEN # SYS_EVENT_OBJECT_NOT_SEEN
examples:
- OBJECT_SEEN
examples:
- type: scannerSystemObjectDetectMsg
data:
eventId: "0123454"
objectDetectEventType: OBJECT_SEEN
schemas:
reqId:
type: string
description: Request ID sent by the client and sent back by the server
examples:
- "123"
eventId:
type: string
description: Unique Id of the event
examples:
- "123450"
connectionId:
type: string
description: Connection ID to identify the session
examples:
- "1278248556"
apiVersionStr:
type: string
description: Version of the API
examples:
- "1.0"
applicationVersionStr:
type: string
description: Version of the Scanner application
minLength: 1
examples:
- "DR941630"
serialNumber:
type: string
# language=markdown
description: The serial number of the device
minLength: 1
maxLength: 32
examples:
- "G23HBCXKE"
buildVersion:
type: string
description: Software Build Version
examples:
- "9698e41a5b"
pingMsg:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- pingMsg
data:
type: object
required:
- reqId
properties:
reqId:
$ref: "#/components/schemas/reqId"
examples:
- type: pingMsg
data:
reqId: "123"
pongMsg:
type: object
required:
- type
- data
properties:
type:
type: string
description: Type of message
enum:
- pongMsg
data:
type: object
required:
- reqId
- connectionId
- apiVersionStr
- applicationVersionStr
- serialNumber
- buildVersion
properties:
reqId:
$ref: "#/components/schemas/reqId"
connectionId:
$ref: "#/components/schemas/connectionId"
apiVersionStr:
$ref: "#/components/schemas/apiVersionStr"
applicationVersionStr:
$ref: "#/components/schemas/applicationVersionStr"
serialNumber:
$ref: "#/components/schemas/serialNumber"
buildVersion:
$ref: "#/components/schemas/buildVersion"
examples:
- type: pongMsg
data:
reqId: "123"
connectionId: "1278248556"
apiVersionStr: "1.0"
applicationVersionStr: "DR941630"
serialNumber: "G23HBCXKE"
buildVersion: "9698e41a5b"