node-red-contrib-xkeys_button 0.3.3
Xkeys button node for Node-RED using DCDP
This is the first of a group of Node-RED nodes to enable access to X-keys physical devices using the DCD Protocol.
It is planned to have a dedicated Node-RED node for each X-key event of interest (button, jog, joystick, etc.). These will communicate, using MQTT, with a lightweight DCD Protocol server, whose sole purpose is to mediate access to any physically attached X-keys devices.
This dcdp_button node encapsulates button events from any or specific X-keys devices.
Installation
This node requires dcdp-server version 0.1.1 to be running. Please follow the instructions at the dcdp-server development repository to install it or, to upgrade an existing installation, see the xkeys-server upgrade instructions.
The node-red-contrib-dcdp_button node itself is best installed from Node-RED's Palette manager. Go to the Palette manager's Install tab and search for node-red-contrib-dcdp_button; then Install it once found. If not found, press the Refresh module list button (two semicircular arrows) and search again.
When installed, a new xk button will be found in the palette tab in a dedicated Xkeys category.
Usage
An xkeys_button-test flow is provided in the examples directory using an xkeys_button configured to process button events from any Xkeys device. The output feeds a switch node which routes button events according to the received payload's buttonid. Buttonid 1 goes to switch output 1, buttonid 2 to output 2, ..., buttonid 8 to output 8. Each of those outputs feed into debug nodes named b1, b2, ..., b8. Button events can then be monitored in the Debug messages tab. A button event with buttonid 1 will be reported by debug node b1, buttonid 2 by debug node b2 etc.
The full msg.payload of the dcdp_button node is as follows:
{ device: NAME, vendor_id: VID, product_id: PID, unit_id: UID, duplicate_id: DUPID, control_id: BUTTONID, action: TYPE }
where
NAME is an abbreviated name of the source device e.g. XK12JOG, which represents the XK-12 Jog & Shuttle device
VID is the Vendor ID of the source device e.g. 1035 for P.I. Engineering (Xkeys)
PID is the Product ID of the source device e.g. 1062 for the XK-12 Jog & Shuttle device
UID is the Unit ID of the source device, typically 0 from the factory but assignable 0-255
DUPID is a server assigned number to distinguish duplicate attached devices (same VID,PID,UID)
BUTTONID is the button number which caused the event
TYPE is the type of event that occurred. Button events may be either down or up types.
With this output from the dcdp_button node, the switch node in the example flow is able to use the msg.payload.buttonid field to route each event to the corresponding output.
Issues
When configuring the node, a drop down list of possible devices shoud be available. If not, instead displaying just a note to Press Deploy button to see device list, first follow that advice. If that is unsuccessful (still no list of possible devices), then check the status of the dcdp-server by running the command sudo systemctl status dcdp-server in a terminal. Typical output of a normally running xkeys-server will be:
pi@pi3b:~ $ sudo systemctl status dcdp-server
● dcdp-server.service - Run dcdp-server as background service
Loaded: loaded (/etc/systemd/system/dcdp-server.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2021-10-14 09:31:55 AEST; 23h ago
whereas a non-running dcdp-server will show something like:
pi@pi3b:~ $ sudo systemctl status dcdp-server
● dcdp-server.service - Run dcdp-server as background service
Loaded: loaded (/etc/systemd/system/dcdp-server.service; enabled; vendor preset: enabled)
Active: failed (Result: timeout) since Fri 2021-10-15 08:41:37 AEST; 19s ago
If necessary, (re)start the dcdp-server with sudo systemctl restart dcdp-server
Authors and acknowledgment
Many thanks to P.I. Engineering for generous financial support and donation of several X-keys devices for development and testing.
License
MIT
