2. Status Dashboard and Instructions

2.1. Status Dashboard

The status dashboard is essentially a controller named “fairino_hardware_state_broadcaster” that starts automatically with the plugin by default. It monitors all status feedback interfaces within the plugin at a frequency of 500 Hz and publishes the data as topics, with the message type name being “fairino_hardware_state_broadcaster/msg/HardwareState”.

Table 2-1 Specific Message Definitions

Field Name	Data Types	Physical Meaning and Business Interpretation
Header	std_msgs/Header	Includes timestamp and coordinate system information for high-precision time synchronization of data frames.
joint_names	string[]	Joint name. Corresponds to the joint name defined in the URDF to ensure data mapping remains in correct order.
errorcode	int32[]	Single-axis servo error code. Records the independent alarm status of each joint driver (e.g., single-axis overload/encoder abnormality).
position	float64[]	Actual position feedback. The motor’s true position reading (in rad or m).
velocity	float64[]	Actual speed feedback. The motor’s true speed reading (in rad/s or m/s).
effort	float64[]	Actual current/torque feedback. Estimated actual output force of the motor.
sensortorque	float64[]	Sensor torque feedback. If equipped with dual encoders or external joint torque sensors, this represents the actual physical torque.
stateword	uint16[]	Servo Status Word. Strictly conforms to the EtherCAT CiA 402 standard state machine dictionary (e.g., 0x0237 indicates Operation Enabled).
opmode	int32[]	Servo operation mode. For example, 8 represents CSP (Cyclic Synchronous Position), and 10 represents CST (Cyclic Synchronous Torque).
command_position	float64[]	Command position. The target position for this joint recently issued by the ROS 2 controller. Subtracting it from “position” yields the “tracking error.”
command_velocity	float64[]	Command velocity. The feedforward velocity commanded by the ROS 2 controller.
command_torque	float64[]	Command torque. The target feedforward torque issued by the ROS 2 controller.
version_major	float64	Major version number. The core major version of the underlying hardware or firmware.
version_minor	float64	Minor version number. Functional update iteration number.
version_minor2	float64	Revision number. Minor patch or bug fix number.
hex_error_code_current_error_code	int32	Current system fatal/operational fault code. Corresponds to a 32-bit hexadecimal code. When non-zero, immediately triggers full-arm brake engagement and dumps a fault snapshot.
hexerrorcode_curwarncode	float64	Current system general warning code. Corresponds to a 32-bit hexadecimal code (e.g., trajectory peak clipping triggered). Recorded and reported only; does not interrupt motion.
generalio_di	uint32	General-purpose digital input (DI). Represents the status of multiple digital inputs (e.g., safety door, external button) via a 32-bit binary mask.
generalio_ai	float64	General-purpose analog input (AI). Digital reading of analog signals in the range of 0–10 V or 4–20 mA.
Interface485_Feedback485	float64	RS-485 interface feedback: Used for reading back communication data from end-effector smart grippers or external serial sensors.
interfacecan_feedbackcan	float64	CAN bus interface feedback. Peripheral communication data or status feedback from expanded CAN nodes.
interfacesdo_sdoreaddata	float64	SDO reads data. Parameter values returned after querying the EtherCAT acyclic data object (SDO) dictionary.
interfacesdo_sdostatus	float64	SDO communication status. Indicates whether the SDO asynchronous read/write request has successfully handshaked or encountered an error.
interfaceGripper1_act	float64	The act status of the left-arm gripper ( requires an arm model with an end plate )
interfaceGripper1_id	float64	The id( of the left-arm gripper requires an arm model with an end plate )
interfaceGripper1_cmdnum	float64	Left-arm gripper command number ( requires an arm model with an end plate )
interfaceGripper1_curpos	float64	Current position of left arm gripper(Arm model with end plate required)
interfaceGripper1_curtor	float64	Current motor torque of left arm gripper(requires arm model with end plate)
interfaceGripper1_done	float64	Whether the current command execution of the left arm gripper is completed(The arm model needs to have an end plate)
interfaceGripper1_error	float64	Current error code of left arm gripper ( requires arm model with end plate )
interfaceGripper2_act	float64	Right-arm gripper’s act status ( requires arm model with end plate )
interfaceGripper2_id	float64	The id( of the right-arm gripper requires an arm model with an end plate )
interfaceGripper2_cmdnum	float64	Right arm gripper command number ( requires an arm model with end plate )
interfaceGripper2_curpos	float64	Current position of right arm gripper(Arm model with end plate required)
interfaceGripper2_curtor	float64	Current motor torque of right-arm gripper(requires arm model with end plate)
interfaceGripper2_done	float64	Whether the current command execution of the right-arm gripper has been completed(The arm model must have an end plate)
interfaceGripper2_error	float64	Current error code of right arm gripper ( requires arm model with end plate )
freedrive1_flag	float64	Left-arm drag button triggers flag, 1 indicates trigger ( requires arm model with end plate )
freedrive2_flag	float64	Right-arm drag button triggers flag, 1 represents trigger ( requires arm model with end plate )
force_sensor1_linx	float64	Left Arm Torque SensorxDirectional Force(Arm Model with End Plate Required)
force_sensor1_liny	float64	Left Arm Torque SensoryDirectional Force(Arm Model with End Plate Required)
force_sensor1_linz	float64	Left Arm Torque SensorzDirectional Force(Arm Model with End Plate Required)
force_sensor1_rotx	float64	Left Arm Torque SensorxDirectional Torque(Arm Model with End Plate Required)
force_sensor1_roty	float64	Left Arm Torque SensoryDirectional Torque(Arm Model with End Plate Required)
force_sensor1_rotz	float64	Left Arm Torque SensorzDirectional Torque(Arm Model with End Plate Required)
force_sensor2_linx	float64	Left Arm Torque SensorxDirectional Force(Arm Model with End Plate Required)
force_sensor2_liny	float64	Right Arm Torque SensoryDirectional Force(Arm model with end plate required)
force_sensor2_linz	float64	Right Arm Torque SensorzDirectional Force(Arm Model with End Plate Required)
force_sensor2_rotx	float64	Right Arm Torque SensorxDirectional Torque(Arm Model with End Plate Required)
force_sensor2_roty	float64	Right Arm Torque SensoryDirection Torque(Requires Arm Model with End Plate)
force_sensor2_rotz	float64	Right Arm Torque SensorzDirectional Torque(Arm Model with End Plate Required)

Here, “hexerrorcode_curerrcode” is the current system error code. If this value is non-zero, it indicates that an error exists in the system. Since the displayed error code uses decimal notation while the error codes are defined in hexadecimal, the decimal value must be converted to hexadecimal to interpret the corresponding fault information. Below is an explanation of the 32-bit error code structure.

Table 2-2: Description of 32-bit Plugin Error Codes

Byte Position	Name	Values and Their Meanings
[31:24] Byte 4	Severity	0x00 = OK (Normal) 0x01 = INFO (informational message) 0x02 = WARN (General warning, does not interrupt execution) 0x0E = ERROR (Operation failure, motion interruption) 0x0F = FATAL (Fatal fault, triggering emergency stop and safety lock)
[23:16] Byte 3	Subsystem	0x00 = INIT (initialization process) 0x10 = RUN (Running Process) 0x20 = SENSOR 0x30 = HAL (Hardware Abstraction Layer Feedback)
[15:08] Byte 2	MainCode (Main Error Code)	For example: 0x00, 0x01, 0xFF (global broadcast)
[07:00] Byte 1	Subcode (from error code)	Serial number, used to precisely distinguish the specific cause of an error

Note

Note that fatal-level errors currently do not support error recovery; all error-level issues can be recovered via the server’s “reseterror” command; warning-level messages are indicated by “curwarncode” but do not interrupt system operation.

Table 2-3 Fatal-Level Fault Codes

Complete Hexadecimal Value	Fault Interpretation	Troubleshooting and Resolution Guidelines
0x0F000001	Parameter reading exception, invalid parameter	Before startup, did you manually modify the configuration file, or is the configuration file corrupted? It is recommended to rerun the “frconfig” command and use the configuration file provided by Faou to configure the slave station.
0x0F000002	Invalid slave station format; failed to parse gear ratio using regular expression.	Before startup, did you manually modify the configuration file, or is the configuration file corrupted? It is recommended to rerun the “frconfig” command and use the configuration file provided by Faou to configure the slave station.
0x0F000004	Failed to initialize shared memory or open semaphore	The HAL library failed to initialize properly. Please contact FAO technical support for troubleshooting.
0x0F000008	Reading initial state and checksum error	The invoked HAL library version is incorrect. Please upgrade using the Faao-provided update package and then restart.
0x0F000010	Error reading initial slave status information; check the EtherCAT topology.	Error in verifying the number and type of slave stations. Please check whether the currently loaded configuration matches the actual hardware and confirm that the EtherCAT cable is connected to the controller at power-on.
0x0F000020	Error: Reading initial state shared memory object is empty	HAL library exited. Please contact Faou technical support for troubleshooting.
0x0F000040	Timeout reading initial state	HAL library exited. Please contact Faou technical support for troubleshooting.
0x0F100001	Shared Memory Watchdog Timeout	The HAL library has gone offline or the underlying driver process has crashed. Check whether the underlying igh process is running normally and verify whether the IPC shared memory mechanism is blocked.
0x0F100101	Slave Information and Checksum Errors	CRC verification failure for the servo data packet obtained at the lower layer. Pay special attention to whether the bus network cable is loose, whether the RJ-45 connector is intact, or whether the cable is subject to strong electromagnetic interference.
0x0F100102	Abnormal number or type of slave stations	The actual number/model of physically scanned joints is inconsistent with the topology defined in the YAML configuration file. Check whether the configuration file is loaded correctly.
0x0F100103	Status shared memory pointer is null	Memory mapping failed. The ROS 2 hardware_interface failed to correctly mount the shared memory address for reading the robotic arm’s status.
0x0F100201	Instruction shared memory pointer is null	Memory mapping failed. The ROS 2 hardware_interface cannot correctly mount the shared memory address for issuing motion commands.

Note

Note that immediately after system startup, the parsed error codes may not be found in the table above—for example, 0x0F00005 may appear. This error code is a combination of 0x0F00001 and 0x0F00004, because multiple operations during system initialization may each fail; however, before the system fully starts up, these errors cannot be reported immediately and are instead accumulated cumulatively, resulting in such composite error codes appearing after initialization.

Table 2-4 ERROR-Level Error Codes

Complete Hexadecimal Value	Fault Interpretation	Troubleshooting and Resolution Guidelines
0x0E10FF01	Drive Failure (Global Broadcast)	0xFF indicates a broadcast alarm for any axis. Possible causes include overcurrent, overload, excessive torque due to collision, or encoder disconnection. Refer to the individual-axis error code to pinpoint the specific joint.
0x0E100001	Soft Emergency Stop Triggered	Logical emergency stop triggered. The host computer or teach pendant issued an emergency stop command, causing the underlying system to immediately interrupt the current motion queue to ensure safety.
0x0E100002	Instruction queue is too long	Interpolation buffer overflow. The host computer sends trajectory points too densely or sets the control frequency too high, causing timeout in the underlying consumer processing. Please check the controller’s execution frequency setting.

Table 2-5 Warning (WARN)-Level Error Codes

Complete Hexadecimal Value	Warning Interpretation	Troubleshooting and Resolution Guidelines
0x02100001	Large instruction step (triggering clipping)	The positional difference between two consecutive points issued by the planner exceeds the underlying system’s maximum velocity/acceleration limits, triggering forced peak clipping and smoothing. This may cause a negligible deviation between the actual and intended trajectory.
0x02100002	Instruction queue write failure	Excessively high instantaneous concurrency causes the system to fail to push interpolation points into the lock-free queue within an extremely short time, potentially resulting in brief motion stuttering.

2.2. Command Server

The instruction server is a controller that starts automatically with the plugin system upon boot-up, named “fairino_hardware_command_controller.” It provides an action server externally named “command,” using a custom interaction message format:

Table 2-6 Custom Interactive Message Format

string command	Request (Goal) – String command, e.g., “Enable(1)”
string error_code	Result – Controller-specific 16-bit hexadecimal error code, e.g., “0xC000”
float32 progress	Feedback – Execution Progress (0.0 ~ 100.0)

Table 2-7 Supported Instructions

Instruction Name	In-depth Feature Description	Input Parameter Description
activateController	Activate the specified ROS 2 controller by calling the controller_manager service to transition the target controller’s state from inactive to active.	args[0]: Controller name (String) Example: fairino_trajectory_controller
Deactivate controller	Deactivate the specified ROS 2 controller. Switch the running controller’s state to inactive, commonly used for control authority handover (e.g., switching out trajectory control and switching in impedance control).	args[0]: Controller name (String) Example: fairino_trajectory_controller
enable	Robot Enable (Servo ON). Send a command to the lower-level controller to close the relay, power up the joint servo motors, and enable torque output.	When no parameters are provided, all joints are enabled; when parameters are provided, joints are enabled according to bit positions (e.g., 1 enables joint 1, 2 enables joint 2, 4 enables joint 3, 8 enables joint 4, and 7 enables joints 1, 2, and 3).
disable	Robot servo disable (Servo OFF). Cuts off torque output from the servo motors, causing the robotic arm to engage the brake.	Same usage as the enable function
setdo	Configure digital output to control the IO pin levels of the robot control cabinet or end-effector, enabling activation of peripheral devices (e.g., grippers, welding torches, relays).	args[0]: IO port index/name args[1]: Status (“1”/”true” for on, “0”/”false” for off)
zeroing	Perform zero-point calibration of the robotic arm. Trigger the underlying homing logic to enable joints to automatically locate the mechanical origin and reset the absolute encoder offset.	Same usage as enable
reset error	Error reset. When the underlying system triggers an ERROR alarm causing brake engagement, invoking this command clears the underlying error flag and restores the system to standby mode, provided the physical fault has been resolved.	No parameters
frconfig	Dynamically generate the robot’s core configuration files. Launch the background Python script to parse the YAML configuration and dynamically generate the URDF model and controller_manager configuration files.	args[0] (optional): The configuration file name under the /opt/fairino_art_plugin/config directory. If omitted, the default file “fairino_config.yaml” is used, equivalent to frconfig(fairino_config.yaml).
upgrade plugin	Automatically upgrade underlying drivers and plugin packages. Extract the incoming ZIP package, clean up the old environment, overwrite the new code to the /opt system directory, and automatically fix permissions for .sh and executable files.	args[0]: The absolute path of the upgrade package (.zip). Example: [“/tmp/update_v2.zip”]
PackLog	One-click packaging of system logs and dump snapshots. Compresses fault snapshots and system runtime logs from /home/fairino/plugin_log/ into a single archive file for easy copying and export by on-site personnel.	No parameters (or optionally specify the target export path)
record data	Control the user’s high-frequency data recorder. Enable or disable a 20 MB circular data recording queue in memory for capturing high-precision joint position, torque, and status waveforms.	args[0]: Action command. Only “start” or “stop” is accepted (case-insensitive).
switch mode	Switch the servo control mode. Note that joint servos support position and torque modes, while modular servos support position and speed modes. If the parameters of the specified servo do not match the allowed modes, an error will be returned.	args[0]: Mode name; “position” for position mode, “velocity” for velocity mode, “torque” for torque mode. args[1]: Slave mask; switches modes for slaves whose indices correspond to the bit positions set to 1 in the mask.
reboot	Restart command	No parameters
shutdownsys	Power-off command	No parameters
getecatcommstatus	Obtain ethercat communication information, used to assist in diagnosing ethercat communication status	No parameters
enablevelff	Enable the specified velocity feedforward（disabled by default）,plugin calculates the velocity feedforward by differentiating the position command and sends it to the motor，to reduce the position tracking delay。It is only effective in position control mode。	Same usage as the enable function
disablevelff	Disable robot velocity feedforward function	Same usage as the enable function

Similarly, according to the instruction-server interaction format described above, each string instruction has a corresponding string feedback value—a 16-bit error code system, whose specific functions are detailed in the table below:

Table 2-8 Specific Function Table

Return Value	Trigger Scenario Definition	Common Troubleshooting and Resolution Recommendations
0xC000	Execution succeeded. The command was fully launched and completed successfully.	No action required; the host computer can continue issuing subsequent procedures.
0xC010	Invalid parameter or injection prevention intercepted. The input parameter is empty or contains dangerous shell characters.	Check the parameters sent by the host computer to ensure they contain only valid file paths or plain text.
0xC011	Dependent service is unavailable. The ROS 2 internal service being called (e.g., controller_manager) is offline or not ready.	Check whether the target node is alive, or wait until the system has fully booted before issuing commands.
0xC012	Hardware status is abnormal. An error or disabled state was detected at the underlying level when issuing commands requiring hardware cooperation.	Please first check the hardware alarm codes for fairino_hardware, then reset the hardware and try again.
0xC013	Command timeout. The command did not complete within the specified time (e.g., download, system response, etc.).	Check the network connection or whether the system load is too high.
0xC020	Controller switching failed. The soft switch (e.g., from joint space to Cartesian space controller) was rejected by the system.	Check whether the controller name is spelled correctly, or whether there is a port conflict on the controller.
0xC021	Zero calibration timeout.	Checking if the plugin is running normally
0xC030	Configuration generation failed. The Python script failed to parse the YAML or generate the URDF/controller configuration.	Check whether the YAML format is correct, and whether the file has been manually tampered with or contains garbled characters.
0xC040	Failed to extract the upgrade package. The unzip command returned a non-zero exit code.	Check whether the .zip file path is correct, whether the archive is corrupted, or whether the /tmp space is full.
0xC041	Directory overwrite failed. An error occurred while the plugin upgrade attempted to overwrite the /opt/… directory.	Check the directory permissions and ownership (whether the owner is fairino) or whether it is occupied.
0xC050	Failed to package logs. An error occurred while collecting and compressing dump files and system runtime logs.	Check the permissions of the target storage path and the remaining disk capacity.
0xC060	Data recording operation failed. The recorddata(start/stop) command processing failed or a write exception occurred.	Check whether the /tmp/record_data directory is writable, or whether a deadlock exists in memory.
0xC0FE	Unknown command. The host computer sent a command that the Action Server cannot parse.	Alignment of the communication protocol interface documentation between the host computer and the slave computer.
0xC0FF	An exception was thrown at the lower level. A severe crash occurred inside C++ or a script, or the process was forcibly terminated by the system.	Check the host’s dmesg or the node’s standard output to troubleshoot segmentation faults (segfaults) or missing dependencies.