> For the complete documentation index, see [llms.txt](https://edgex-api-advantech.gitbook.io/edgex-api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edgex-api-advantech.gitbook.io/edgex-api-doc/device-connection/scanner-sdk.md). # 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. ![](https://1210863923-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Ldahy90A1eekcr5A2U8%2Fuploads%2Fh7vMZFE1eozaTiZ2KQxN%2Fimage.png?alt=media\&token=f96a8e6f-0231-4d73-934a-3cfa3ab92e17) \ **\[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"}

]

}

Calling =>localhost: 500Calling =>03/api/getscannerlist

Return =>

{

“total”:”0”,

"id": "",

"model": "",

"errorcode": "0001"

}

| ### **Set current scanner**

Calling =>localhost: 50003/api/setcurscanner/1

Return =>

{

"id":"1",

"model":"UM800L",

“model\_type”:”2”

"errorcode":"0000"

}

Calling => localhost: 50003/api/setcurscanner/3

Return =>
{

"id": "",

"model": "",

“model\_type”:””,

"errorcode": "0002"

}

### Get current scanner

Calling =>localhost: 50003/api/getcurscanner

Return =>
{

"id":"1",

"model":"UM800L",

“model\_type”:”2”,

"errorcode":"0000"

}

Calling =>localhost: 50003/api/getcurscanner

Return =>
{

"id": "",

"model": "",

“model\_type”:””,

"errorcode": "0001"

}

| ### Upload mapping table

Calling =>localhost: 50003/api/uploadmappingtable

Return =>
\[

{"id":"001","name":"Albert001","errorcode":"0000"},

{"id":"002","name":"Albert002","errorcode":"0000"},

{"id":"003","name":"Albert003","errorcode":"0000"}

]

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"

}

Calling =>localhost: 50003/api/getscanid

Return =>
{

"id": \[""

"timestamp": "",

"errorcode":"0004"

}

| ### Get name by ID

Calling =>localhost: 50003/api/ getnamebyid/4771234567890

Return =>
{

"id":"4771234567890",

"name":"Michelle",

"errorcode":"0000"

}

Calling =>localhost: 50003/api/ uploademployeeinfo

Return =>
{

"id": "",

"name": "",

"errorcode": "0013"

}

| ### Download mapping table

Calling =>localhost: 50003/api/downloadmappingtable

Return =>
04138B145A6434808A,Albee

0413A53A5A6434808A,Ash

0413A53A5A6434838A,Alice

0455A53A5A6434333A,Bell

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

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"

}

]

}

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",

}

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

{

"region":10

}

Return =>

{

"region":0,

"errorcode":"0001"

}

### Get Region Frequency

Calling => localhost:50003/api/getregionfreq

Return =>

{

"region": 3,

"errorcode": "0000",

}

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

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

{

"timeout": 100

}

Return =>

{

"timeout": 100,

"errorcode": "0000",

}

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