Web Socket Client Service

WEB SOCKET CLIENT SERVICE

Introduction

How it works

Events

Configuration

Advanced JSON conf

Persist settings

Examples

WEB SOCKET CLIENT SERVICE

Introduction

The WebSocketClientService is a feature that allows the device to maintain a live, constant connection with a remote server, so that tag reads can be sent out immediately as they happen, instead of waiting for the server to ask for them. It is available since AdvanNet version 2.12.44.

This feature works in two modes, depending on a single setting called "isCustom":

• Normal mode (default): The device connects to the server and continuously sends tag reads to it. If the server sends anything back, the device simply takes note of it (logs it) but does not act on it in any way.

• Custom mode: Everything from Normal mode still applies, but additionally the remote server is able to remotely control the reader itself, starting or stopping scanning, and adjusting reading settings such as which antennas are active, transmit power, filters, and more.

Custom mode is an advanced option meant for specific integrations where the server needs to actively drive/configure the reader remotely, rather than just receive data from it.

How it works

Normal mode

1. The device opens and keeps open a live connection to the configured server address.

2. As tags are read and events happen (device status changes, alarms, GPI signals, etc.), they are prepared and sent to the server following a format that was configured for this connection.

3. If the server sends any message back, the device simply records it in its logs for informational purposes.

4. If the connection is lost for any reason (network issue, server restart, etc.), the device will automatically try to reconnect.

Custom mode

Everything above still happens, plus:

1. Session handshake: As soon as the connection is established, the device automatically identifies itself to the server and requests permission to operate (this is called "allocating" the device). Until the server confirms this, no data will be sent and no remote commands will be accepted.

2. Remote commands: Once confirmed, the server can send commands to:

3. Start scanning, optionally along with reading configuration (see below).

4. Stop scanning.

5. End the session entirely, after which the connection is closed. Every command sent by the server is acknowledged by the device (confirming success or reporting an error).

6. Automatic reconnection and keep-alive: A background process checks periodically (every 30 seconds) whether the connection and session are still valid, and reconnects/re-identifies automatically if needed. This ensures the connection recovers on its own after temporary network problems.

7. Protection against outdated readings: Whenever reading settings are changed remotely, the device makes sure that any tag reads captured under the previous settings are discarded, so they never get mixed in with data from the new settings.

Reading settings configurable remotely (Custom mode only)

When the server asks the device to start scanning, it can also include specific reading instructions, such as:

• Which antennas should be active (Up to 4 antennas without muxes).

• The RF mode.

• The search mode.

• How often batches of reads should be reported.

• Tag TTL: How long a tag is "remembered" to avoid reporting the same one multiple times in a short time.

• The transmit power used for reading.

• An EPC filter to only read tags matching the desired criteria.

• Which extra details should be included in each reported read (such as TID, antenna number, read count, signal strength, or phase).

Events

Besides tag reads, the WebSocketClient can also send out various system and device events. 

The following event types are supported:

• Tag and inventory read events:

  • TAG_READ: Generated from regular inventory operations.

  • TAG_READ_ANTENNA_1, TAG_READ_ANTENNA_2, TAG_READ_ANTENNA_3, TAG_READ_ANTENNA_4: Antenna-specific tag read events.

• AdvanPay events:

  • TAG_ADPY_PAYMENT

  • TAG_ADPY_RETURN

  • TAG_ADPY_READ

• EAS events:

  • TAG_ALARM: EAS alarm triggered by an active tag.

  • TAG_ALARM_ANTENNA_1, TAG_ALARM_ANTENNA_2, TAG_ALARM_ANTENNA_3, TAG_ALARM_ANTENNA_4: Antenna-specific EAS alarm events.

• GPI and Sensor events:

  • GPI: The direction of the change (whether it went from high to low, or from low to high) is available in the "ctx_subtype" field of the payload.

  • SENSOR: Sensor measurement events.

  • MULTI_SENSOR: Aggregated sensor read event.

• System timer events (available from version 2.3.18-11 onward)
  These are periodic events fired at fixed intervals, useful for sending regular heartbeats/status updates independently of tag activity:

  • SYSTEM_1MINUTE_TIMER

  • SYSTEM_5MINUTE_TIMER

  • SYSTEM_10MINUTE_TIMER

  • SYSTEM_30MINUTE_TIMER

  • SYSTEM_60MINUTE_TIMER

• Tag operations, lifecycle and tracking events

  • TAG_DIRECTION: Generated when the system detects the direction a tag moved (e.g., in vs. out).

  • TAG_MOVE: Generated when tag movement across zones/antennas is tracked.

  • TAG_SCAN: Generated on tag scan operations.

  • TAG_SCAN_ALARMED: Tag scan event specifically flagged with an alarm condition.

  • TAG_WRITE: Generated when data is successfully written to a tag.

  • TAG_KILLED: Generated when a tag is permanently deactivated/killed.

• Other:

  • UWB: Ultra Wide Band events

  • ADVW: See AdvanView Events

  • TAG_GENERIC: See Custom Events

  • TAG_GENERIC_2: See Custom Events

Configuration

These are the main settings available for this connection:

Required fields are marked with *

Connection

The connection options are:

• Protocol*: options are

  • WS

  • WSS

• Host*

• Port: port 0 will default to:

  • 80 for ws

  • 443 for wws

• User

• Password

• Connection timeout: maximum connection timeout, expressed in ms. Default: 1500 ms.

JSON config*

This is a JSON List of Maps, each Map with the following elements:

• event: fully qualified name of the event we want to use

• path: path starting with /

• params: aditional arguments for the url.  Example of the format -> "params": "'param1=value1&param2=value2'" .

• body: javascript expression that defines a variable named body. 

The javascript expression is evaluated with an injected context filled with real time data

Before entering the JSON config in the device it is recommendable to double check it's correctly formed by using a JSON validator like this one: https://jsonlint.com/

Before validating the JSON format please delete all tabulations and row jumps. You can do this by searching "\n" and "\t" in a text editor and deleting them.

See possible events in the previous point of this page.

Available context variables are:

Read related data:

• ctx_tags - List of read tag objects (TagDataHolder array) in the current inventory batch 

• ctx_type - Message type constant ("TAG_READ") 

• ctx_devid - Device identifier 

• ctx_devip - Device IP address 

• ctx_devmac - Device MAC address 

• ctx_reportdetail_tid - Flag indicating whether TID reporting detail is enabled 

• ctx_reportdetail_antenna - Flag indicating whether antenna reporting detail is enabled 

• ctx_reportdetail_n - Flag indicating whether read count (N) reporting detail is enabled 

• ctx_reportdetail_peakrssi - Flag indicating whether peak RSSI reporting detail is enabled 

• ctx_reportdetail_phaseshift - Flag indicating whether phase shift reporting detail is enabled

Event related data:

• ctx_epc - Tag EPC in hexadecimal format 

• ctx_tid - Tag TID memory bank in hexadecimal format 

• ctx_user - Tag User memory bank in hexadecimal format 

• ctx_sku - SKU/GTIN decoded from the EPC 

• ctx_serial - Serial number decoded from the EPC 

• ctx_uri - Decoded EPC pure URI representation 

• ctx_oldepc - Previous EPC before encoding/rewrite 

• ctx_newepc - New EPC after encoding/rewrite 

• ctx_type - Event type name (e.g. EPC_READ, GPI, ALARM, DIRECTION, DEVICE_STATUS) 

• ctx_subtype - Event subtype descriptor 

• ctx_time - Event local timestamp in milliseconds 

• ctx_date - Event date string 

• ctx_utc - Event UTC timestamp in milliseconds 

• ctx_locid - Location identifier 

• ctx_locx - Location X coordinate 

• ctx_locy - Location Y coordinate 

• ctx_locz - Location Z coordinate 

• ctx_devid - Device identifier 

• ctx_devip - Device IP address 

• ctx_devmac - Device MAC address 

• ctx_devgateway - Device network default gateway IP address 

• ctx_devdns - Device configured DNS server addresses 

• ctx_devstatus - Device operational status 

• ctx_alarms - List of active alarms 

• ctx_sensors - Sensor status and reading payload data 

• ctx_cpu - CPU diagnostic metrics and usage 

• ctx_disk - Disk usage and storage diagnostic metrics 

• ctx_memory - Memory RAM usage diagnostic metrics 

• ctx_uptime - Host operating system uptime 

• ctx_osversion - Host operating system version 

• ctx_advannetversion - AdvanNet software version 

• ctx_advannetuptime - AdvanNet runtime uptime

Per-tag related data:

• ctx_tags[i].getEPC() - Returns the tag EPC as a hexadecimal string 

• ctx_tags[i].getEPCBytes() - Returns the tag EPC as a raw byte array 

• ctx_tags[i].getTID() - Returns the tag TID memory bank as a hexadecimal string 

• ctx_tags[i].getTIDBytes() - Returns the tag TID memory bank as a raw byte array 

• ctx_tags[i].getUser() - Returns the tag User memory bank as a hexadecimal string 

• ctx_tags[i].getMemBytes() - Returns the tag User memory bank as a raw byte array 

• ctx_tags[i].getSKU() - Returns the decoded SKU/GTIN from the EPC 

• ctx_tags[i].getSerial() - Returns the decoded serial number from the EPC 

• ctx_tags[i].getURI() - Returns the pure EPC URI string (e.g. urn:epc:tag:...) 

• ctx_tags[i].getAntenna() - Returns the antenna port number where the tag was read 

• ctx_tags[i].getMux1() - Returns the multiplexer level 1 port 

• ctx_tags[i].getMux2() - Returns the multiplexer level 2 port 

• ctx_tags[i].getRSSI() - Returns the last received RSSI value in dBm 

• ctx_tags[i].getPeakRSSI() - Returns the highest peak RSSI value recorded during the batch 

• ctx_tags[i].getPhase() - Returns the RF phase shift value 

• ctx_tags[i].getReadCount() - Returns the total number of reads for this tag in the batch 

• ctx_tags[i].getUTC() - Returns the tag read UTC timestamp in milliseconds 

• ctx_tags[i].getTime() - Returns the tag read local timestamp in milliseconds 

• ctx_tags[i].getUTCFormatted() - Returns the tag read UTC date-time formatted as string 

• ctx_tags[i].getTimeFormatted() - Returns the tag read local date-time formatted as string 

• ctx_tags[i].getREPUVE() - Returns the 8 alphanumeric characters extracted from EPC for REPUVE 

• ctx_tags[i].getNIV() - Returns the 17 alphanumeric characters extracted from TID for NIV 

• ctx_tags[i].getCreation() - Returns the nanosecond creation timestamp of the tag read object

Send options

The send options are:

• Batch window time: Duration of each batching window, starting with the first tag read of the batch, during which tag reads are accumulated before being sent.

• Send one by one: options are

  • true: in case of TAG_READ, it sends each reads in a different request

  • false: in case of TAG_READ, may send several reads in the same request

• Inventory tag TTL: in case of TAG_READ, do not send the same combination of EPC+antenna or EPC+TID if they a previous match is found in the defined time window. Default: 60 seconds. Maximum: 60 seconds.

• Use Antenna in tag TTL: when enabled, the TTL cache key includes the antenna port. This means the same EPC read on different antennas will be sent separately.

• Use TID in tag TTL: when enabled, the TTL cache key includes the TID. This means tags with the same EPC but different TID will be sent separately.

• Re-send: in case of error connections, re-enqueue again the events for later sent

  • The inventory queue has a capacity of ~20000 items. The event queue has a capacity of ~10000 items.

  • Items can be in the queue for a maximum of 10 minutes, they are then removed permanently.

• Expected response code: expected HTTP response code from the server. If set to 0, any successful response is accepted.

Advanced JSON conf

This setting allows to configure additional parameters:

• isCustom: specifies whether custom configuration behavior is enabled

• debug: to enable additional debug information

• verbose: to enable verbose logging of every queued and sent item

• debugTransport: Enables or disables detailed WebSocket transport logging

• proxyHost: the IP address or hostname of the proxy server to route HTTP/HTTPS requests through.

• proxyPort: the port number on which the proxy server is listening for client connections.

• reQueueMismatchedRequests: when true, requests that receive an unexpected response code or entity will be re-enqueued for retry (instead of being discarded). Default: false.

An example of a JSON conf is:

{"isCustom":true, "debug":true,"debugTransport":true}

Persist settings

Once the current settings seems to work as desired, please do not forget to persist system settings using the "Save current" button at the top.

Examples