Skip to content

RFID device setup

Purpose

This guide is for field integrators preparing a new embedded RFID unit for DiamondTracker. It applies to JavaRFID-based networked RFID devices such as SmartBoard, SmartBox, SmartFridge, and related storage units. It does not apply to USB-attached products such as SmartPad.

In practice there are two different setup paths:

  • Create a new image: used when preparing or updating the base embedded image that will later be cloned to multiple devices
  • Configure a cloned image: used for the normal field workflow, where the device already contains the software stack and only needs site-specific network access and unit registration

Most deployments use the cloned-image path.

1. Normal field workflow: configure a cloned image

Use this path when the embedded image already contains the installed JavaRFID runtime, the configured systemd services, and the standard provisioning setup.

1.1 First boot and physical installation

Place the device where it will be deployed and connect the hardware required for that model:

  • power supply
  • Ethernet, if the site uses wired networking
  • the RFID board USB or serial connection
  • badge reader or other optional serial peripherals when the device uses them

On first boot, the device should either:

  • obtain network connectivity through Ethernet, or
  • expose the provisioning hotspot so you can enter local Wi-Fi credentials

1.2 Network access

If the site provides Ethernet, connect the cable before or during first boot.

If Ethernet is not available, connect to the provisioning hotspot exposed by the device and use the local setup page to enter the site Wi-Fi credentials. The hotspot is the bootstrap path for devices that start without a working uplink network.

1.3 Verify the JavaRFID service

The cloned image is expected to already contain the runtime and installed services. Verify that the main service is running:

sudo systemctl status javarfid --no-pager
journalctl -u javarfid -f

At this stage the logs should show the device serial number and the detected hardware type.

1.4 Register the unit through the legacy Java interface

Once the device is online and the JavaRFID service is running, open the legacy JavaRFID web interface served by the device:

http://<device-ip>:8080/

Then use the hidden maintenance flow:

Settings -> Maintenance -> Register Unit

Use that screen to register the unit in the backend database.

For this step, the only input you need is the device serial number. The backend URL is expected to already be configured on the device, and the target company is inferred from the login token of the user currently accessing the maintenance page.

After registration completes, the device should appear in the backend under the same company as the logged-in user and be ready for the normal DiamondTracker workflow.

2. Image creation workflow

Use this path only when building or refreshing the golden image that will later be cloned to multiple units.

2.1 Prepare the base image

Flash or clone the approved embedded operating-system image onto the target storage. The base image is expected to provide the operating-system components required by JavaRFID, including NetworkManager and the persistent hotspot profile used for Wi-Fi provisioning when no uplink is available.

Validate one image first before cloning it to multiple devices.

2.2 Install the JavaRFID runtime

Copy the JavaRFID runtime archive to the embedded device and unpack it under /opt:

sudo useradd --system --home /opt/javarfid --shell /usr/sbin/nologin javarfid || true
sudo usermod -aG dialout javarfid
sudo tar -xzf javarfid-runtime.tar.gz -C /opt
sudo chown -R javarfid:javarfid /opt/javarfid

Create the persistent configuration and state directories:

sudo install -d -m 0750 -o javarfid -g javarfid /etc/javarfid
sudo install -d -m 0750 -o javarfid -g javarfid /var/lib/javarfid
if [ ! -f /etc/javarfid/smartserver.properties ]; then
  sudo install -m 0640 -o javarfid -g javarfid /opt/javarfid/smartserver.properties.example /etc/javarfid/smartserver.properties
fi

Install the service files and the self-update helper:

sudo cp /opt/javarfid/javarfid.service /etc/systemd/system/javarfid.service
sudo cp /opt/javarfid/javarfid-update.service /etc/systemd/system/javarfid-update.service
sudo cp /opt/javarfid/wifi-provisioning.service /etc/systemd/system/javarfid-wifi.service
sudo cp /opt/javarfid/serialbridge-monitor.service /etc/systemd/system/javarfid-serialbridge.service
sudo cp /opt/javarfid/javarfid-usb-network@.service /etc/systemd/system/javarfid-usb-network@.service
sudo cp /opt/javarfid/99-usb-onplug.rules /etc/udev/rules.d/99-usb-onplug.rules
sudo install -m 0440 /opt/javarfid/javarfid-update.sudoers /etc/sudoers.d/javarfid-update
sudo chmod 0755 /opt/javarfid/update_runtime.sh /opt/javarfid/serialbridge.sh /opt/javarfid/serialbridge-monitor.sh /opt/javarfid/usb_onplug.sh
sudo systemctl daemon-reload
sudo udevadm control --reload-rules

2.3 Configure JavaRFID defaults for the image

Edit /etc/javarfid/smartserver.properties and set the baseline backend and device configuration required for the image:

backend_enabled=on
backend_url=https://your-backend-host
backend_login=your-device-login
backend_password=your-device-password

Use http:// or https:// for backend_url. Do not use ws:// or wss://; JavaRFID derives the Socket.IO connection endpoint from the HTTP base URL.

If the model uses a badge reader and Linux autodetection is not sufficient, add the required serial-port override before capturing the image.

2.4 Enable the services

sudo systemctl enable --now javarfid
sudo systemctl enable --now javarfid-wifi
sudo systemctl enable --now javarfid-serialbridge

Once the golden image is validated, clone it to the remaining units and use the cloned-image workflow for the site-specific deployment.

3. Completion checklist

The setup is complete when all of the following are true:

  • the device has a working network connection
  • javarfid.service is active
  • JavaRFID logs show the expected serial number and hardware type
  • the unit has been registered through Settings -> Maintenance -> Register Unit
  • the device appears under the correct company in the backend

At that point the unit is ready for the normal DiamondTracker workflow.

For the lower-level technical details behind this guide, refer to the JavaRFID documentation:

  • Odroid deployment and service installation
  • Wi-Fi provisioning behavior
  • backend Socket.IO configuration
  • self-update helper installation