Low Level Reader Protocol (LLRP) library for node.
Synopsis & Motivation
LLRP (Low Level Reader Protocol) is a binary protocol published by EPCglobal Inc. to define the standard communication interface between RFID readers (servers) and clients. For more infomration, check out the LLRP standard definition.
The LLRP ToolKit (LTK) project was created back in 2008 by a group of companies and universities to help the development of LLRP-based applications. The toolkit provided support for many languages including C, C++, Java, Perl, etc. A year later, however, Node.js came around and opened the door to countless possibilities and proved to be one of the easiest and fastest ways to IoT development.
LLRP makes the perfect use case for JavaScript, given that it's a message-oriented protocol with many messages that are best handled asynchronously. See reader reports handling in the example below.
Example
llrpjs helps create programs for both servers (readers) and clients. The following example shows how to connect to a reader and collect EPC data of RFID tags.
const { LLRPClient, LLRPCore } = require("llrpjs");
const ADD_ROSPEC = require("./ADD_ROSPEC.json");
// create a client
const reader = new LLRPClient({ host: "192.168.7.2" });
// print RFID tags
reader.on("RO_ACCESS_REPORT", msg => {
let tagReportDataList = msg.getTagReportData();
if (!Array.isArray(tagReportDataList)) {
tagReportDataList = [tagReportDataList]
}
for (let tagReportData of tagReportDataList) {
let epc = tagReportData.getEPCParameter();
console.log(`EPC: ${epc.getEPC()}`);
}
});
reader.on("READER_EVENT_NOTIFICATION", msg => {
// handle reader event notification messages here
});
reader.on("error", err => {
// handle errors
});
reader.on("connect", () => {
console.log("connected");
})
reader.on("disconnect", () => {
console.log("disconnected");
});
/** Main */
(async () => {
try {
// connect to reader
await reader.connect();
// wait for connection confirmation
await checkConnectionStatus();
// delete all existing ROSpecs (if any)
await reader.transact(new LLRPCore.DELETE_ROSPEC({
data: { ROSpecID: 0 /** all */ }
}));
// factory reset
await reader.transact(new LLRPCore.SET_READER_CONFIG({
data: { ResetToFactoryDefault: true }
}));
// add ROSpec defined in "./ADD_ROSPEC.json"
await reader.transact(new LLRPCore.ADD_ROSPEC(ADD_ROSPEC));
// enable ROSpec
const { ROSpecID } = ADD_ROSPEC.data.ROSpec;
await reader.transact(new LLRPCore.ENABLE_ROSPEC({
data: { ROSpecID }
}));
// start ROSpec
await reader.transact(new LLRPCore.START_ROSPEC({
data: { ROSpecID }
}));
console.log("Press ctrl+c to exit");
} catch (e) {
console.error(e);
process.exit(1);
}
})();
/**
* wait for a READER_EVENT_NOTIFICATION message
*/
const checkConnectionStatus = async () => {
let msg = await reader.recv(7000);
if (!(msg instanceof LLRPCore.READER_EVENT_NOTIFICATION)) {
throw new Error(`connection status check failed - unexpected message ${msg.getName()}`);
}
const status = msg.getReaderEventNotificationData().getConnectionAttemptEvent()?.getStatus();
if (status != "Success") {
throw new Error(`connection status check failed ${status}`);
}
return;
}
process.on("SIGINT", async () => {
// request termination
const rsp = await reader.transact(new LLRPCore.CLOSE_CONNECTION);
if (rsp instanceof LLRPCore.CLOSE_CONNECTION_RESPONSE) {
const status = rsp.getLLRPStatus();
console.log(`${status.getErrorDescription()} - ${status.getStatusCode()}`)
}
// make sure it's disconnected
if (reader.socketWritable) await reader.disconnect();
});Static typing
llrpjs is written in TypeScript and provides static typing support:
JSON and JSON Schema support
llrpjs commits to the same goals set by the LTK project. However, llrpjs attempts at accomplishing some of these goals differently:
JSON over XML
The LTK project used XML to represent human-readable LLRP documents. However, given that JSON has out-of-the-box support in Node.js as well as many APIs and document-oriented databases (e.g. MongoDB), it makes sense to use it over XML in llrpjs. llrpjs uses a one-to-one mapping of the same XML format used in LTK:
llrpjs JSON (full example)
{
"$schema": "https://llrpjs.github.io/schema/core/encoding/json/1.0/llrp-1x0.schema.json",
"id": 103, "type": "ADD_ROSPEC",
"data": {
"ROSpec": {
"ROSpecID": 1,
"Priority": 0,
"CurrentState": "Disabled",
// ...
}
}
}LTK XML (full example)
<ADD_ROSPEC MessageID='103'
xmlns:llrp='http://www.llrp.org/ltk/schema/core/encoding/xml/1.0'
xmlns='http://www.llrp.org/ltk/schema/core/encoding/xml/1.0'>
<ROSpec>
<ROSpecID>1</ROSpecID>
<Priority>0</Priority>
<CurrentState>Disabled</CurrentState>
<!-- ... -->
</ROSpec>
</ADD_ROSPEC>JSON Schema over XSD
The LLRP JSON schema is generated from the source LTK definition and supports all types and formats. VSCode supports JSON schema out of the box:
CLI Tools
On installation, the package makes two CLI programs available: llrp2json and json2llrp. These commands can be used to convert binary llrp messages to JSON and the other way around. Use --help flag to get information on how to use.
Development
llrpjs uses the same definition llrp-1x0-def.xml set by the LTK project to generate runtime type definitions and schema. This library is written in TypeScript and allows dynamic static typing using a given LLRP definition. That said, llrpjs in itself is definition-agnostic, meaning that the code itself only conforms to the meta schema that was set by the LTK project (llrpdef.xsd) and any definition that complies with the meta schema can be used to generate types for llrpjs.
Check out llrpjs-tools for more information.
Author
Haytham Halimeh
- Github: @haytham43
- LinkedIn: @haytham-halimeh
Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
TODO
- Tool to convert from llrpjs JSON to LTK XML and vice versa
- Vendor definitions support
- Documentation
Disclaimer
This project is independent.