Skip to content

SDK reference ​

This page is the API map to keep open next to your editor: every public method of the Nextwaves SDK 1.0.0, arranged by job. If this is your first pass through the documentation, start with the quickstart and reading tags and come back here. All five packages share one set of concepts; method names follow each language's conventions.

Reader states ​

Nearly every "when may I call this" rule on this page reduces to one diagram:

The reader only accepts configuration commands while idle. To change configuration mid-inventory, stop first, then change, detailed in reading tags and deduplication.

Creating a reader ​

LanguageConstructorNotes
Pythoncreate_reader(port, baudrate=115200, timeout=0.5, log_level=logging.INFO)Returns a configured NRNReader; the direct form is NRNReader(port, baudrate, timeout, logger)
TypeScriptcreateNRNReader({ baudrate, timeout, onLog })Returns NRNWebSerial; no port parameter since the browser picks the port
Gonrn.NewNRNReader(portName, baudrate)NewNRNReaderWithTransport accepts any io.ReadWriteCloser with SetReadTimeout and ResetInputBuffer, handy for test doubles
RustNRNReader::new(port_name, baudrate)Returns Result<NRNReader>
C++nrn::NRNReader(port, baudrate = 115200, timeout_ms = 500)Call open() before use

Connecting ​

JobPythonTypeScriptGoRustC++
Open the portopen()connect()opens in the constructoropens in the constructoropen()
HandshakeConnect_Reader_And_Initialize()connect()ConnectAndInitialize()connect_and_initialize()connect_and_initialize()
Closeclose()disconnect()Close()closes on dropclose()
Port statusuart.is_open()getReaderInfo().isConnectederrors on the next writeerrors on the next writeis_open()

NRNWebSerial.connect() opens the port and performs the handshake in one call. NRNWebSerial.isSupported() reports whether the browser has the Web Serial API.

The five packages do not compute the frame checksum the same way in 1.0.0. Python and TypeScript use CRC16 polynomial 0x1021; Go, Rust, and C++ use 0x8005. Every command those three packages send, and the validity check in their ParseFrame / parse_frame, uses 0x8005. Test the Go, Rust, or C++ package against your reader before you depend on it, see CRC16.

Reader identity and abilities ​

python
info = reader.Query_Reader_Information()
ability = reader.query_rfid_ability()

info carries serial_number, power_on_time_sec, baseband_compile_time, app_version, os_version, and app_compile_time. ability carries min_power_dbm, max_power_dbm, antenna_count, frequencies, and rfid_protocols.

Equivalents: queryReaderInformation() (TypeScript, which has no ability query), QueryReaderInformation() and QueryRFIDAbility() (Go), query_reader_information() and query_rfid_ability() (Rust and C++). Query abilities before setting power: the reader declares its own valid range, and the values you set should sit inside it.

Inventory ​

python
reader.start_inventory_with_mode(antenna_mask=[1, 2], callback=on_tag)
reader.stop_inventory()
reader.is_inventory_running()
LanguageStartAntenna parameterStop
Pythonstart_inventory_with_mode(antenna_mask, callback)port list counted from 1stop_inventory()
TypeScriptstartInventory(antennaMask, callback)port array counted from 1stopInventory()
GoStartInventory(antennaMask, callback)32-bit mask, built with BuildAntennaMaskStopInventory()
Ruststart_inventory(antenna_mask, callback)32-bit mask, built with build_antenna_maskstop_inventory()
C++start_inventory(antenna_mask, callback, include_tid)32-bit mask, built with build_antenna_maskstop_inventory()

Python and Web Serial deliver tags through the callback with their built-in read loop. In Go, Rust, and C++ 1.0.0, the start inventory call only sends the start command: the callback is accepted but never invoked. To receive tags in those languages, add the receive loop from the appendix. In Python, call is_inventory_running() only after a start or stop, because the flag it reads does not exist before then.

Tag data ​

ts
interface TagData {
  epc: string;
  pc: string;
  antenna_id: number;
  rssi: number | null;
  tid?: string;
  phase?: number;
  frequency?: number;
}
  • epc: the EPC bank contents as an uppercase hex string.
  • pc: the Protocol Control word in hex, see the glossary.
  • antenna_id: the antenna port that read the tag, counted from 1. Keep this field throughout so every read maps to an area.
  • rssi: signal strength in dBm, already converted from the raw byte by the SDK. null (None in Python) when the reader omits the RSSI parameter.
  • tid: the TID bank contents in hex, present only when TID reading was requested.
  • phase: the tag's phase in radians, converted from the raw 0 to 128 value.
  • frequency: the channel frequency in MHz.

Go uses TagData{EPC, PC, AntennaID, RSSI, TID, Phase, Frequency} with optional fields as pointers; Rust and C++ use Option<T> and std::optional<T>. Python returns a dict with exactly the TypeScript interface's keys.

A tag sitting in the read zone produces a notification on every scan round, so before turning reads into business events, apply your deduplication window per reading tags and deduplication.

Power ​

python
reader.configure_reader_power({1: 30, 2: 25}, persistence=True)
powers = reader.query_reader_power()

query_reader_power returns a port-to-dBm map, for example {1: 30, 2: 25, 3: 30, 4: 30}. persistence=True stores the setting across power cycles. Python rejects ports outside 1 to 64 and power outside 0 to 33 dBm, and returns False. TypeScript has configureReaderPower(antennaPowers, persistence) / queryReaderPower(). Go, Rust, and C++ pair up as ConfigurePower(powers, persist) / QueryPower() and configure_power / query_power.

Antennas ​

python
mask = reader.build_antenna_mask([1, 4, 7, 32])   # 0x80000049
reader.enable_ant(4, save=True)
reader.disable_ant(2, save=True)
reader.query_enabled_ant_mask()
reader.save_antenna_mask(mask)

The mask is a 32-bit bitmask with antenna n at bit n - 1. The free functions BuildAntennaMask (Go) and build_antenna_mask (Rust, C++) perform the same conversion. Web Serial converts internally: just pass the port array to startInventory.

RF band, frequency, and baseband ​

This method group belongs to the Python package. The clean deployment pattern for browser clients: configure the reader once from Python or the vendor tool, save with persist, and let the Web Serial client only run inventory.

MethodPurpose
query_rf_band() / set_rf_band(band_code, persist)Read and set the regional band
query_working_frequency()Read the active channel list
select_profile(profile_id) / get_profile()Baseband profile, RF_PROFILES holds ids 0, 1, 2
configure_baseband(speed, q_value, session, inventory_flag) / query_baseband_profile()Speed, Q, session, and inventory flag, see the glossary
get_session()The current Gen2 session
set_filter_settings(repeated_time_ms, rssi_threshold) / query_filter_settings()The reader-side dedup window and RSSI threshold

The SDK transmits exactly the configuration you set, so choosing the band and channels legal at the site is the design's responsibility; the final check list lives in the production checklist.

Writing EPCs ​

The Python package has three writing paths:

python
reader.write_epc_tag(epc_hex, antenna_id=1, match_epc_hex=None)        # explicit start word
reader.write_epc_tag_auto(new_epc_hex, match_epc_hex=None)             # computes PC bits and start word
reader.write_epc_to_target_auto(target_tag_epc, new_epc_hex)           # scan for a tag, then write

write_epc_tag returns a dict with success, result_code, result_msg, and failed_addr. validate_epc_hex(epc_hex) raises ValueError on non-hex characters or an odd number of digits, and returns the bytes padded to a whole word.

check_write_epc(epc_hex) does not verify a write in 1.0.0. It starts an inventory on antenna 1 with a callback that only logs whether the expected EPC was seen, returns True at once, and leaves that inventory running. Read the tag back with your own inventory callback, compare the EPC, then stop the inventory. Always read back after writing, and only write once the encoded value and the physical target item are independently verified; the full procedure is in EPC encoding.

GPIO ​

ConfigureGPO(gpoID, state) and QueryGPI(gpiID) exist in Go; configure_gpo / query_gpi in Rust and C++, for readers with GPIO ports, say to light a lamp or open a barrier. The Python and Web Serial packages have no GPIO methods in 1.0.0. Until they do, run the GPIO part through a small Go, Rust, or C++ process, subject to the checksum note under Connecting.

Beeper ​

python
reader.set_beeper(BEEPER_MODES["BEEP_AFTER_TAG"])
reader.get_beeper()

BEEPER_MODES holds QUIET (0x00), BEEP_AFTER_INVENTORY (0x01), and BEEP_AFTER_TAG (0x02). In the 1.0.0 Python package, 0 sends a buzzer-off command and 1 starts the buzzer at once. 2 only records the mode inside the SDK and sends nothing; the inventory loop does not read it, so no beep per tag follows. get_beeper() returns True when the stored mode is 1 or 2.

Errors ​

Python and TypeScript define a typed exception hierarchy:

python
from nrn import (
    NextwavesSDKError,     # the root class
    ConnectionError,       # opening the port, losing the port
    ProtocolError,         # invalid data on the wire
    ConfigurationError,    # invalid power, mask, band
    TagOperationError,     # write or lock failed
)

TypeScript mirrors the structure with the root class NRNWebSerialError and four matching subclasses. Rust returns Result<T, NRNError>, Go returns wrapped error values, and C++ reports through bool returns and empty result structs.

In the 1.0.0 Python package, ConnectionError is the only class from this hierarchy that is raised: when the port fails to open, or when you send or receive on a closed port. The other three classes are defined but not raised yet. Most methods log the problem and return False, {}, or a result dict, so check return values. Errors inside the inventory thread, such as a USB reader pulled mid-inventory, are logged and the loop keeps running; they reach neither the tag callback nor your thread. Watch the tag rate to detect a lost reader.

Logging ​

python
reader.set_log_level(logging.DEBUG)

TypeScript takes an onLog(level, message) callback in the constructor options, C++ uses set_log_callback. Go uses the standard log package, Rust the log crate facade. Debug-level logging records the raw data of every read, so enable it only while debugging and keep it off in production, where logs may carry product and customer identifiers.

The low-level utilities for building and dissecting data, for tool authors and receive loop writers, live in the NRN reader protocol appendix.

SDK information ​

NRNReader.get_sdk_info() (Python) and NRNWebSerial.getSDKInfo() (TypeScript) return the SDK's name and version. Log the value at session start, so every support ticket carries the SDK build next to the reader's firmware.

Sense Inventory operations and RFID integration documentation