Scanner SDK

Content

• Introduction

• Hardware devices support list

• File structure

• RESTful API

Introduction

The Scanner SDK programming guide will lead the user to interact with the Scanner SDK through the RESTful API. The user can obtain the data (ID) scanned by the current Scanner through the RESTful API, and can use the database imported by the user through simple settings (Config.ini). The Scanner SDK uses the ID to quickly match the name, and the scan data can also be stored directly to the cloud database through the EdgeX connection.

Hardware devices support list

*1 => The region range mapping to the following

1 : USA 902~928 MHz

2 : Taiwan 922~928 MHz

3 : China 920~925 MHz

4 : China2 840~845 MHz

5 : Europe 865~868 MHz

*2 => The antenna power range mapping to the following

GIGA Tek UM800L -19~27 dBm

JogTek TM915 -2~25 dBm

File structure

The file structure consists of three parts.

uploads:

User upload data will be stored in this folder, please don’t change the folder’s name or location that will cause Scanner SDK service error.

output:

The location that the debug log outputs to.

ScannerSDK.exe:

Main executable file, invoke the Scanner SDK to start the service and get ID from the scanner.

Config.ini:

General setting lists as follows =>

[Scanner]:

Set current use scanner, default is "0", in this version, current scanner support lists refer to the "Hardware devices support list".

[RFID]:

The RFID device comport is, default is "COM7"

[RFIDCOM_BAUDRATE]:

For the RFID baud rate for customized setting, please set it before the API /api/getscanid, if the user doesn’t set this tag via API /api/setscannercomportbaudrate/ , Scanner SDK will use the default baud rate to handle the scanner.

[BARCODECOM]:

The barcode device comport is, default is "COM28".

[BARCODECOM_BAUDRATE]:

For the barcode baud rate for customized setting, please set it before the API /api/getscanid, if the user doesn’t set this tag via API /api/setscannercomportbaudrate/ , Scanner SDK will use the default baud rate to handle the scanner.

[Lookup]:

Set to "1" to map names or tags with ID from the imported database, Set to "0" to do nothing but ID with scan result, default is "1".

[ToMqtt]:

Set "1" to pass the scan result to the MQTT broker and vice versa.

[MqttIP]:

Set MQTT broker IP address, default is "tcp://10.0.75.1:1883" [MqttIP] IP = tcp://10.0.75.1:1883 for general purposes to DockerNAT for EdgeX, the user also can set your own MQTT broker IP address, which located. This setting will be activation while [ToMqtt] set to "1".

[MqttTopic]:

Set MQTT topic, default is “mqtt_topic”. The user must be assigned the MQTT topic to match the request.

[MqttAutoUpload]:

Set MQTT auto upload after getting scan ID or not, set Enable to upload the current scan result to the MQTT by given MQTT parameter,

Set Disable to stop auto upload of the scan result

Initial flowchart

The user must follow this initial flowchart to staring the Scanner SDK completely. Launch the Scanner SDK and call the API by following the sequences.

RESTful API

The Scanner SDK API located at localhost:50003 while running, and the format of the API is

localhost: 50003/api/{RESTful API function name}/{parameter 1} /… /{parameter N},

and all the returns are package by JSON formats. All the API lists as follows:

Get Scanner SDK version

Example:

Calling =>localhost: 50003/api/getscannersdkversion Return => { "Version": "V2.1.11" }

Get supported scanner list

Example:

• Normal case

Calling => localhost: 50003/api/getsmscannerlist Return => { "total": "3", "device": [ { "id": "0", "model": "ADT007A","model_type":"1","errorcode": "0000"}, ……………… {"id": "2", "model": "TM915","model_type":"2""errorcode": "0000"} ] }

• Failure case

Calling =>localhost: 500Calling =>03/api/getscannerlist Return => { “total”:”0”, "id": "", "model": "", "errorcode": "0001" }

Set current scanner

Example:

• Normal case

Calling =>localhost: 50003/api/setcurscanner/1 Return => { "id":"1", "model":"UM800L", “model_type”:”2” "errorcode":"0000" }

• Failure case

Calling => localhost: 50003/api/setcurscanner/3 Return => { "id": "", "model": "", “model_type”:””, "errorcode": "0002" }

Get current scanner

Example:

• Normal case

Calling =>localhost: 50003/api/getcurscanner Return => { "id":"1", "model":"UM800L", “model_type”:”2”, "errorcode":"0000" }

• Failure case

Calling =>localhost: 50003/api/getcurscanner Return => { "id": "", "model": "", “model_type”:””, "errorcode": "0001" }

Upload mapping table

Example:

• Normal case

Calling =>localhost: 50003/api/uploadmappingtable Return => [ {"id":"001","name":"Albert001","errorcode":"0000"}, {"id":"002","name":"Albert002","errorcode":"0000"}, {"id":"003","name":"Albert003","errorcode":"0000"} ]

• Failure case

Calling =>localhost: 50003/api/uploadmappingtable Return => { "id": "", "name": "", "errorcode": "0001" }

Get scan ID

• Normal case

Single tag usage

Calling =>localhost: 50003/api/getscanid Return => { "id": [ "3400300833B2DDD9014000000044" ], "timestamp": "2022-06-10 15:46:14", "errorcode":"0000" }

Multi-tags usage

Calling => localhost: 50003/api/getscanid Return => { "id": [ "3400300833B2DDD9014000000055", "3400300833B2DDD9014000000044" ], "timestamp": "2022-06-10 15:46:14", "errorcode": "0000" }

• Failure case

Calling =>localhost: 50003/api/getscanid Return => { "id": ["" ], "timestamp": "", "errorcode":"0004" }

Get name by ID

• Normal case

Calling =>localhost: 50003/api/ getnamebyid/4771234567890 Return => { "id":"4771234567890", "name":"Michelle", "errorcode":"0000" }

• Failure case

Calling =>localhost: 50003/api/ uploademployeeinfo Return => { "id": "", "name": "", "errorcode": "0013" }

Download mapping table

• Normal case

Calling =>localhost: 50003/api/downloadmappingtable Return => 04138B145A6434808A,Albee 0413A53A5A6434808A,Ash 0413A53A5A6434838A,Alice 0455A53A5A6434333A,Bell

• Failure case

Calling =>localhost: 50003/api/downloadmappingtable Return => { "id": "", ”name”:””, "errorcode": "0014" }

Output current scan result

• Normal case

Calling =>localhost: 50003/api/outputscanresult/123456/2/4714947000196/37/1/1 Return => { "station_id": "123456", "scanner_id": "2", "scan_id": "4714947000196", "name": "Calpis water", "thermal_value": "37", "timestamp": "2021-01-22 14:19:33", "errcode": "0000" }

• Failure case

Calling =>localhost: 50003/api/outputscanresult/123456/2/4714947000196/37/1/1 Return => { "station_id": "", "scanner_id": "", "scan_id": "", "name": "", "thermal_value": "", "timestamp": "", "errcode": "0013" }

Set scanner comport

Notice: This API also stores the value into cfg.ini file simultaneously in those tags : [RFIDCOM] / [BARCODECOM].

• Normal case

Calling =>localhost:50003/api/setscannercomport/COM3/COM4 Return => { "barcode_com": "COM3", "barcode_baudrate": "115200", "rfid_com": "COM4", "errorcode": "0000" }

• Failure case NA

Get scanner comport

• Normal case

Calling =>localhost:50003/api/getscannercomport Return => { "barcode_com": "COM3", "barcode_baudrate": "115200", "rfid_com": "COM4", "rfid_baudrate": "115200", "errorcode": "0000" }

• Failure case NA

Set scanner comport baud rate

Notice: This API also stores the value into cfg.ini file simultaneously in those tags : [RFIDCOM_BAUDRATE] / [BARCODECOM_BAUDRATE].

• Normal case

Calling =>localhost:50003/api/setscannercomportbaudrate/9600/115200 Return => { "barcode_com": "COM3", "barcode_baudrate": "9600", "rfid_com": "COM4", "rfid_baudrate": "115200", "errorcode": "0000" }

Set MQTT parameter

Notice: This API also stores the value into cfg.ini file simultaneously in those tags : [MqttIP] / [MqttTopic] / [MqttAutoUpload]

• Normal case

Calling =>localhost:50003/api/setmqttpara with Body in JSON format { "MqttAddress": "tcp://10.0.75.1:1883", "MqttTopic": "mqtt_topic", "MqttAutoUpload": "Enable" } Return => { "mqtt_address": "tcp://10.0.75.1:1883", "mqtt_topic": "mqtt_topic", "mqtt_auto_upload": "Enable", "errorcode": "0000" }

Note : If the tag [MqttAutoUpload] set to “Enable”, the Scanner SDKwill send current scan result to the MQTT address with follows JSON format =>

Single tag usage:

[ { "name":"Scanner_Model", "value":"Jogtek ADT007A" }, { "name":"Scanner_Type", "value":"RFID" }, { "name":"Scanner_Scancode", "value": [ "E007C4CE7835799D" ] } ]

Multi-tags usage:

[ { "name":"Scanner_Model", "value":"UM800L" }, { "name":"Scanner_Type", "value":"UHFRFID" }, { "name":"Scanner_Scancode", "value":[ "3400E007C4CE7835799D; 3400E007C4CE7835800D;" ] } ]

Get MQTT parameter

• Failure case

Calling => localhost:50003/api/getmqttaddress Return => { "mqtt_address": "tcp://10.0.75.1.1883", “mqtt_topic”: “mqtt_topic”, “mqtt_auto_upload”: “Enable”, "errorcode": "0000" }

Get Scanner SDK Status

Notice: please follow the initial flowchart before calling this API

• Normal case

Calling => localhost:50003/api/getscannersdkstatus Return => { "total": "1", "device": [ { "status":"activate", "VID": "10C4", “PID”: ”EA60”, "ID": "6" } ] }

• Failure case

Calling => localhost:50003/api/getscannersdkstatus Return => { "total": "0", "device": [ { "status":"deactivate", "VID": "0000", “PID”: ”0000”, "ID": "0" } ] }

Set Region Frequency

Notice: Only UHF RFID device support this command.

• Normal case

Calling => localhost:50003/api/setregionfreq with BODY in JSON format { "region": 3 } Return => { "region": 3, "errorcode": "0000", }

• Failure case

Calling => localhost:50003/api/setregionfreq with BODY in JSON format { "region":10 } Return => { "region":0, "errorcode":"0001" }

Get Region Frequency

Notice: Only UHF RFID device support this command.

• Normal case

Calling => localhost:50003/api/getregionfreq Return => { "region": 3, "errorcode": "0000", }

• Failure case

Calling => localhost:50003/api/getregionfreq Return => { "region":0, "errorcode":"0037" }

Set Antenna Power

Notice: Only UHF RFID device support this command.

Normal case

Calling => localhost:50003/api/setantennapower with BODY in JSON format

{

"power": 3

}

Return =>

{

"power": 3,

"errorcode": "0000"

}

Failure case

Calling => localhost:50003/api/ setantennapower with BODY in JSON format

{

"power": 29

}

Return =>

{

"power": 0,

"errorcode": "0001"

}

Get Antenna Power

Notice: Only UHF RFID device support this command.

Normal case

Calling => localhost:50003/api/ getantennapower

Return =>

{

"power": 3,

"errorcode": "0000"

}

Failure case

Calling => localhost:50003/api/getantennapower

Return =>

{

"power": 0,

"errorcode": "0015"

}

Set UART read timeout

Notice: Only UHF RFID device support this command.

• Normal case

Calling => localhost:50003/api/setregionfreq with BODY in JSON format { "timeout": 100 } Return => { "timeout": 100, "errorcode": "0000", }

• Failure case

Calling => localhost:50003/api/setuarttimeout with the BODY in JSON format { "timeout": 214748364899996654654654564654 } Return => { "timeout": 0, "errorcode": "0001", }

Cancel Operation

Notice: Only works in UHF RFID devices while the getScanID command is issued.

• Normal case

Calling =>localhost:50003/api/ canceloperation Return => { "errorcode": "0000", }

Appendix

Error Table:

Error code	Error message
0000	Request success
0001	Parameter error
0002	ID out of range
0003	Please set current scanner first
0004	Get file from client failed
0005	Create temp file error
0006	Read file content error
0007	Open system path error
0008	Read data from csv failed
0009	OS rename csv file error
0010	OS remove csv file error
0011	OS rename csv file error 2
0012	No current scan id
0013	Name mismatch with ID
0014	Download file failed, please import file first
0015	Comport open failed
0016	Read data from comport failed
0017	Read data is empty
0018	Unknown error
0019	Connect to broker error
0020	JSON marshal failed
0021	Write data to comport failed
0022	Get RFID FW version no response
0023	Set RFID protocol mode failed
0024	Read RFID protocol mode failed
0025	Set RFID protocol type failed
0026	Read RFID protocol type failed
0027	Set RFID protocol type 2 failed
0028	Read RFID protocol type 2 failed
0029	Set RFID protocol type 3 failed
0030	Read RFID protocol type 3 failed
0031	Write Jogtek get ISO14443A UUID failed
0032	Read Jogtek get ISO14443A UUID failed
0033	Write Jogtek get ISO15693 UUID failed
0034	Read Jogtek get ISO15693 UUID failed
0035	Save to config.ini file failed
0036	Scan result without any ID exist
0037	Get/set region failure
0038	Module not matched
0039	CRC checksum error
0040	Get/set antenna power failure
0041	User cancel the operation
0042	Feature unsupported
0043	Set back to command mode failed