8. Peripherals

8. Peripherals

8.1. End-Effector Lua Custom Open Protocol

8.1.1. Overview

A hardware interface is provided at the robot end for connecting peripherals via 485 communication. Currently supported peripherals include grippers, rotary grippers, force sensors, welding handles, and other devices. All these end-effector devices can be adapted by writing a Lua open protocol to achieve protocol adaptation, enabling control of the peripheral and obtaining its status.For the SmartTool welding handle, users can also choose to log in to the web page to configure key functions and automatically generate an open protocol file. The generated protocol will be automatically applied to the end.

8.1.2. Operation Steps

Step1: Navigate to System Settings -> About -> Firmware Upgrade interface, select the end-effector firmware .bin file, and upgrade the end-effector firmware.

Important

First, confirm whether the end-effector firmware version FV2.010.06 or later meets the requirements. If the version does not meet the requirements, upgrade the corresponding software firmware; otherwise, firmware upgrade is not necessary.

Before uploading the end-effector firmware upgrade package, it is necessary to disable the robot and then enter boot mode.

Figure 8.1‑1 Upgrade End-Effector Firmware

Step2: Open the WebApp, click “Initial Setup”, “Peripherals” in sequence, and select the end-effector peripheral to be configured (e.g., gripper). The control type for peripherals includes two options: pre-adapted devices and peripheral open protocol:

Pre-adapted Devices: Use the robot controller for communication. No upload or application is required.
Peripheral Open Protocol: Users write a Lua-based open protocol for the end-effector to be adapted to achieve communication control. The end-effector protocols are divided into two categories: one is protocols uploaded by the user, and the other is built-in protocols preset in the robot.Starting from version 3.9.2, users do not need to perform verification and encryption operations on the Lua protocol to be uploaded to the end using additional software; they can upload it directly. Previously verified and encrypted protocols can still be uploaded and used normally. The robot will actively distinguish whether the file has been verified and encrypted. If it has not been verified, the robot will verify and encrypt it before uploading and applying it to the end. If it is already encrypted, it will be uploaded and applied to the end directly.

Figure 8.1‑2 Gripper Control Type

Step3: Enter the content interface for Peripherals -> Gripper/Force Sensor/Welding Handle. Click on the “Custom Protocol” card to enter the interface. Upload the Lua end-effector open protocol, select the Lua end-effector open protocol to be uploaded, and perform the upload operation.

Important

The uploaded file name must start with AXLE_LUA_.

Step4: Configure the end-effector communication parameters, including baud rate, data bits, stop bits, etc. After configuration, click the “Configure” button.

Figure 8.1‑3 Configure End-Effector Communication Parameters

The detailed end-effector communication parameters are as follows:

Baud Rate: Supports 1-9600, 2-14400, 3-19200, 4-38400, 5-56000, 6-67600, 7-115200, 8-128000; The end-effector Rs485 driver chip is a low-speed 485, baud rate cannot be >200k;
Data Bits: Supports (8,9), commonly 8 is used;
Stop Bits: 1-1, 2-0.5, 3-2, 4-1.5, commonly 1 is used;
Parity Bit: 0-None, 1-Odd, 2-Even, commonly 0 is used;
Timeout: 1~1000ms, this value needs to be set reasonably in combination with the peripheral device;
Timeout Retries: 1~10, mainly for timeout retransmission, reducing sporadic exceptions and improving user experience;
Periodic Command Interval: 1~1000ms, mainly used for the time interval between each issuance of periodic commands;

Step5: Enable the End-Effector Lua by clicking the “Enable” button.

Figure 8.1‑4 Enable End-Effector Lua

When an exception occurs in the Lua file, a “End-Effector Lua File Exception” warning is prompted, and “Ignore/Recover” processing can be performed. Turn off the Lua enable button to close the warning prompt.

Figure 8.1‑5 Lua File Exception

When the device type is a gripper, status monitoring can be performed.

Turn on “Status Monitoring”: The gripper status bar on the right displays real-time status information such as gripper running speed, torque, position, etc.

Turn off “Status Monitoring”: The gripper data status bar on the right closes.

Figure 8.1‑6 Status Monitoring

8.2. Gripper

In the “Initial” -> “Peripherals” -> “Gripper” interface, grippers can currently be used via Pre-Adapted Devices and the End-Effector Lua Custom Open Protocol.

8.2.1. Pre-Adapted Devices

Step1: Click “Pre-Adapted Devices” to enter the end-effector peripheral configuration interface. The gripper configuration information includes gripper manufacturer, gripper type, software version, and mounting position. Users can configure the corresponding gripper information according to specific production needs. If the user needs to change the configuration, they can first select the corresponding gripper number, click the “Clear” button to clear the corresponding configuration, and reconfigure according to the requirements;

Figure 8.2‑1 Gripper Configuration

Important

Before clicking to clear the configuration, the corresponding gripper should be in an inactive state.

Step2: After the gripper configuration is completed, the user can view the corresponding gripper information in the gripper information table at the bottom of the page. If a configuration error is found, click the “Clear” button to reconfigure the gripper;

Figure 8.2‑2 Gripper Configuration Information

Step3: Select the configured gripper, click the “Reset” button, after the page pops up indicating the command was sent successfully, then click the “Activate” button. Check the activation status in the gripper information table to determine whether the activation was successful;

Important

When activating the gripper, the gripper must not be holding any object.

Step4: In the program teaching command interface, select the “Gripper” command. In the gripper command interface, the user can select the gripper number they want to control (grippers that have been configured and activated), set the corresponding open/close state, open/close speed, open/close torque, and the maximum waiting time for the gripper action. After completing the settings, click Add to apply. Additionally, gripper activation and reset commands can be added to activate/reset the gripper when running the program.

Figure 8.2‑3 Gripper Command Editing

8.2.1.1. Gripper Program Teaching

No.	Command Format	Comment
1	PTP(template2,100,-1,0)	# Wait for gripping point
2	PTP(template1,100,-1,0)	# Gripping point
3	MoveGripper(1,255,255,0,1000,0)	# Gripper close
4	PTP(template2,100,-1,0)	/
5	PTP(template3,100,-1,0)	# Wait for placement point
6	PTP(template3,100,-1,0)	# Placement point
7	MoveGripper(1,0,255,0,1000,0)	# Gripper open

8.2.2. Gripper Lua End-Effector Protocol Configuration

Open the WebApp, click “Initial Setup”, “Peripherals”, “Gripper”, “Custom Protocol” in sequence. Click “Protocol Management” to configure the end-effector protocol.

The filename uploaded by the user must start with “AXLE_LUA_End”. After uploading, the protocol name in the list will change to start with “Custom_End”. This type of protocol can be downloaded and deleted. Files with duplicate names uploaded by the user will automatically be overwritten with the latest Lua.

Figure 8.2‑4-1 Gripper Custom Protocol Upload

The robot’s preset built-in protocols start with End_ as a prefix. They can only be downloaded, not deleted. The built-in protocols for peripherals (gripper, rotary gripper, suction cup) are shown in the figure below.

Figure 8.2‑4-2 Gripper (Rotary Gripper, Suction Cup) Preset Built-in Protocol

After ensuring the correct protocol is selected, you can disable the robot and apply the open protocol. After application, the robot will automatically enter boot mode and apply the selected protocol to the end-effector. When the page prompts “Upgrade successful, please restart the control box”, you can power cycle the control box.

Figure 8.2‑4-3 Applying the End-Effector Open Protocol to the End-Effector Board

After restarting and entering the WebApp page, the page will display the name of the currently applied protocol. After clicking to enable the end-effector protocol and enabling the device, the end-effector protocol will start running. The Device ID is the Modbus slave address of the end-effector peripheral and needs to be used in conjunction with the content in the protocol.

Figure 8.2‑4-4 Gripper End-Effector Protocol Configuration Display and Enablement

The end-effector board will verify the uploaded Lua protocol. When there is an issue with the Lua file, it will show a “End-Effector Lua File Abnormal” warning. You can choose “Do Not Recover/Recover”. Turn off the Lua enable button to close the warning prompt.

Figure 8.2‑4-5 Gripper End-Effector Protocol Configuration Display and Enablement

8.2.2.1. Example of a Gripper Peripheral’s Lua End-Effector Peripheral Protocol

function Getbit(X,Bit)--Getbit(), extracts the corresponding bit from a byte. Parameters: X: the byte from which to extract the bit; Bit: the bit position to extract (range 0-7)
return ((X&(1<<Bit))>>Bit)
end

function GetOneByte(U32)--GetOneByte(), extracts the data 0x1234, gets its low byte, returns 0x34
return ((U32>>0)&0xFF)
end

function GetTwoByte(U32)--GetTwoByte(), extracts the data 0x1234, gets its high byte, returns 0x12
return ((U32>>8)&0xFF)
end
function GetThreeByte(U32)--GetThreeByte(), extracts the data 0x56781234, extracts and returns 0x78
return ((U32>>16)&0xFF)
end
function GetFourByte(U32)--GetFourByte(), extracts the data 0x56781234, extracts and returns 0x56
return ((U32>>24)&0xFF)
end
X,Speed,Torque=0,0,0
while(1)
do
IwdgTaskHandle()
MainLoop()
UpDownLoadHandle()
SdoRwPara()
EndErrClear()
local BFlag=LuaBreak()
if(BFlag==1)then
break
end--From here to the end of the file LuaGc(), end is fixed syntax

T1={0x01,0x06,0x03,0xE8,0x00,0x09,0xC9,0xBC}--Populate gripper commands (Modbus RTU commands). T1-T5 are respectively: gripper action execution command, gripper initialization command, gripper position command, gripper speed command, gripper torque command
--/Command parsing: T1[1]=0X01, is the gripper address; T1[2]=0x06, write single holding register function code; T1[3], T1[4]: 0x03,0xE8, address of the register to operate for the action execution command; T1[5],T1[6]: 0x00,0x09, data to write to the register; T1[7],T1[8]: 0xC9,0xBC, CRC checksum, needs to be modified according to the gripper user manual
T2={}
T3={}
T4={}
T5={}

T7={0x01,0x03,0x07,0xD0,0x00,0x01,0x84,0x87}--T7-T12, gripper status reading commands, respectively: read gripper status command, read gripper initialization command, read gripper error code command, read gripper position command, read gripper speed command, read gripper torque command
T8={}
T9={}
T10={}
T11={}
T12={}
Rcmd1,Rcmd2,Rcmd3,Rcmd4=GetGripCmd()--Fixed usage, no need for modification. Rcm2 is the gripper address sent by the controller, Rcmd4 is the data sent by the controller
if(Rcmd1==1) then
T1[1]=Rcmd2
T2[1]=Rcmd2
T3[1]=Rcmd2
T4[1]=Rcmd2
T5[1]=Rcmd2

T7[1]=Rcmd2
T8[1]=Rcmd2
T9[1]=Rcmd2
T10[1]=Rcmd2
T11[1]=Rcmd2
T12[1]=Rcmd2                    --**Gripper address update
if (Rcmd3==1) then              --Gripper action execution command
T1[7],T1[8]=CrcValue(T1[1],T1[2],T1[3],T1[4],T1[5],T1[6])--Calculate Modbus RTU command CRC value, two bytes
EndTxGripData(T1[1],T1[2],T1[3],T1[4],T1[5],T1[6],T1[7],T1[8])--End-effector sends command to gripper
DelayMs(10)                                                   --Delay 10ms
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()--End-effector returns the received gripper feedback data to Lua. Specific feedback content needs to be checked in the gripper user manual
GripStateBack(Rxd3)
end
if (Rcmd3==2) then
T2[7],T2[8]=CrcValue(T2[1],T2[2],T2[3],T2[4],T2[5],T2[6])
EndTxGripData(T2[1],T2[2],T2[3],T2[4],T2[5],T2[6],T2[7],T2[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
GripStateBack(Rxd3)
end
if(Rcmd3==3) then
X=Rcmd4
T3[5]=0x00
T3[6]=X
T3[7],T3[8]=CrcValue(T3[1],T3[2],T3[3],T3[4],T3[5],T3[6])
EndTxGripData(T3[1],T3[2],T3[3],T3[4],T3[5],T3[6],T3[7],T3[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
GripStateBack(Rxd3)
end
if (Rcmd3==4) then
Speed=Rcmd4
T4[5]=Torque
T4[6]=Speed
T4[7],T4[8]=CrcValue(T4[1],T4[2],T4[3],T4[4],T4[5],T4[6])
EndTxGripData(T4[1],T4[2],T4[3],T4[4],T4[5],T4[6],T4[7],T4[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
GripStateBack(Rxd3)
end
if(Rcmd3==5) then
Torque=Rcmd4
T5[5]=Torque
T5[6]=Speed
T5[7],T5[8]=CrcValue(T5[1],T5[2],T5[3],T5[4],T5[5],T5[6])
EndTxGripData(T5[1],T5[2],T5[3],T5[4],T5[5],T5[6],T5[7],T5[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
GripStateBack(Rxd3)
end
if(Rcmd3 == 7) then
T7[7],T7[8]=CrcValue(T7[1],T7[2],T7[3],T7[4],T7[5],T7[6])
EndTxGripData(T7[1],T7[2],T7[3],T7[4],T7[5],T7[6],T7[7],T7[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
RxdCrcH,RxdCrcL = CrcValue(Rxd1,Rxd2,Rxd3,Rxd4,Rxd5)
if((A==8)and(Rxd1==Rcmd2)and(Rxd2==0x03)and(Rxd3==0x02)and(Rxd6==RxdCrcH)and(Rxd7==RxdCrcL))then
GripStateBack(Rxd4)
end
end
if(Rcmd3==8) then
T8[7],T8[8]=CrcValue(T8[1],T8[2],T8[3],T8[4],T8[5],T8[6])
EndTxGripData(T8[1],T8[2],T8[3],T8[4],T8[5],T8[6],T8[7],T8[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
RxdCrcH,RxdCrcL = CrcValue(Rxd1,Rxd2,Rxd3,Rxd4,Rxd5)
if((A==8)and(Rxd1==Rcmd2)and(Rxd2==0x03)and(Rxd3==0x02)and(Rxd6==RxdCrcH)and(Rxd7 ==RxdCrcL)) then
GripStateBack(Rxd5)
end
end
if(Rcmd3 == 9) then
T9[7],T9[8]=CrcValue(T9[1],T9[2],T9[3],T9[4],T9[5],T9[6])
EndTxGripData(T9[1],T9[2],T9[3],T9[4],T9[5],T9[6],T9[7],T9[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
RxdCrcH,RxdCrcL = CrcValue(Rxd1,Rxd2,Rxd3,Rxd4,Rxd5)
if((A==8)and(Rxd1==Rcmd2)and(Rxd2==0x03)and(Rxd3==0x02)and(Rxd6==RxdCrcH)and(Rxd7==RxdCrcL)) then
GripStateBack(Rxd5)
end
end
if(Rcmd3 == 10) then
T10[7],T10[8]=CrcValue(T10[1],T10[2],T10[3],T10[4],T10[5],T10[6])
EndTxGripData(T10[1],T10[2],T10[3],T10[4],T10[5],T10[6],T10[7],T10[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
RxdCrcH,RxdCrcL = CrcValue(Rxd1,Rxd2,Rxd3,Rxd4,Rxd5)
if((A==8)and(Rxd1==Rcmd2)and(Rxd2==0x03)and(Rxd3==0x02)and(Rxd6==RxdCrcH)and(Rxd7==RxdCrcL)) then
GripStateBack(Rxd4)
end
end
if(Rcmd3 == 11) then
T11[7],T11[8]=CrcValue(T11[1],T11[2],T11[3],T11[4],T11[5],T11[6])
EndTxGripData(T11[1],T11[2],T11[3],T11[4],T11[5],T11[6],T11[7],T11[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
RxdCrcH,RxdCrcL = CrcValue(Rxd1,Rxd2,Rxd3,Rxd4,Rxd5)
if((A==8)and(Rxd1==Rcmd2)and(Rxd2==0x03)and(Rxd3==0x02)and(Rxd6==RxdCrcH)and(Rxd7==RxdCrcL)) then
GripStateBack(Rxd5)
end
end
if(Rcmd3 == 12) then
T12[7],T12[8]=CrcValue(T12[1],T12[2],T12[3],T12[4],T12[5],T12[6])
EndTxGripData(T12[1],T12[2],T12[3],T12[4],T12[5],T12[6],T12[7],T12[8])
DelayMs(10)
A,Rxd1,Rxd2,Rxd3,Rxd4,Rxd5,Rxd6,Rxd7=EndRxGripData()
RxdCrcH,RxdCrcL = CrcValue(Rxd1,Rxd2,Rxd3,Rxd4,Rxd5)
if((A==8)and(Rxd1==Rcmd2)and(Rxd2==0x03)and(Rxd3==0x02)and(Rxd6==RxdCrcH)and(Rxd7==RxdCrcL)) then
GripStateBack(Rxd4)
end
end
end
LuaGc()
end

8.2.2.2. Device Enable

Step1: Enable Gripper -> Select Gripper ID -> Check the function codes adapted for the gripper -> Click Configure. The configured device displays the Gripper ID and function codes.

Figure 8.2‑4 Configure Gripper

Note

The current supported device address range for the end-effector open function for grippers is 1~8. Before use, adjust the gripper device address via the gripper manufacturer’s upper computer software.

The selected function codes should be queried from the product manual provided by the gripper manufacturer to match the gripper’s adapted functions, and should correspond to the end-effector Lua function codes. For details, please refer to the “End-Effector Lua Adaptation Gripper Instruction Manual”.

Step2: Select Gripper ID -> Reset -> Activate. The gripper performs an initialization. For specific initialization details, please refer to the product manual provided by the gripper manufacturer.

Figure 8.2‑5 Activate Gripper

Step3: Enter Teach Program -> Program Programming -> Add Gripper Motion Command.

Figure 8.2‑6 Add Gripper Motion Command

Figure 8.2‑7 Gripper Motion Command Example

8.2.2.3. Multiple Grippers

Activation and motion control refer to the gripper steps.

Figure 8.2‑8 Configure Multiple Grippers

Note

8.2.2.4. Rotary Gripper

Step1: Enable Gripper -> Select Gripper ID -> Check the function codes adapted for the gripper -> Click Configure. The configured device displays the Gripper ID and function codes.

Figure 8.2‑9 Configure Gripper and Function Codes

Note

The selected function codes should be queried from the product manual provided by the gripper manufacturer to match the gripper’s adapted functions, and should correspond to the end-effector Lua function codes. For details, please refer to “FR05-End-Effector Full Peripheral Protocol-V2.5-20241101.xlsx”.

Figure 8.2‑10 Activate Gripper

Step3: Enter Teach Program -> Program Programming -> Add Rotary Gripper Motion Command.

Figure 8.2‑11 Add Rotary Gripper Motion Command

Figure 8.2‑12 Rotary Gripper Motion Command Example

Note

The rotation turns are absolute rotation turns. The maximum forward rotation turns are 90, and the maximum reverse rotation turns are 90. A reset operation is required after rotation.

8.3. Force Sensor

In the “Initial” -> “Peripherals” -> “Force Sensor” interface, force sensors can currently be used via Pre-Adapted Devices and the End-Effector Lua Custom Open Protocol.

8.3.1. Pre-Adapted Devices

Step1: Click “Pre-Adapted Devices” to enter the end-effector peripheral configuration interface.

The force sensor configuration information includes manufacturer, type, software version, and mounting position. Users can configure the corresponding force sensor information according to specific production needs. If the user needs to change the configuration, they can first select the corresponding number, click the “Clear” button to clear the corresponding information, and reconfigure according to the requirements;

Figure 8.3‑1 Force Sensor Configuration

Important

Before clicking to clear the configuration, the corresponding sensor should be in an inactive state.

Step2: After the force sensor configuration is completed, the user can view the corresponding force sensor information in the information table at the bottom of the page. If a configuration error is found, click the “Clear” button to reconfigure.

Figure 8.3‑2 Force Sensor Configuration Information

Step3: Select the configured force sensor number, click the “Reset” button, after the page pops up indicating the command was sent successfully, then click the “Activate” button. Check the activation status in the force sensor information table to determine whether the activation was successful; Additionally, the force sensor will have an initial value. The user can choose “Zero Calibration” and “Remove Zero” according to usage requirements. Force sensor zero calibration requires ensuring the force sensor is level and vertically downward, and the robot has no configured load.

Step4: After the force sensor configuration is completed, it is necessary to configure the sensor type tool coordinate system. The sensor tool coordinate system values can be directly input and applied based on the distance between the sensor and the end-effector tool center.