JAKA 编程脚本（后文简称为 JKS）是控制节卡机器人的专用编程语言。

用户可以根据 JKS 所规定的语法进行编程来控制机器人。

编程脚本基础

基础语法

标识符

在 JKS 中，标识符不区分大小写，且其命名需满足以下规则：

• 只能使用英文字母、数字和下划线；
• 第一个字符不能是数字；
• 不能将关键字用作标识符；
• 最长支持255个字符，建议不要超过30个字符。

示例:

_var1 = 1
var2  = 1
VAR3  = 1
_2KDDinKAEld74Zl8WzKP = 1
# illegal
4VAR = 1
if = 1

预留关键字

下表展示了在 JKS 中的保留字。

这些保留字不能用作常数或变数，或任何其他标识符名称。

and	exec	not
assert	finally	or
break	for	pass
class	from	print
continue	global	raise
def	if	return
del	import	try
elif	in	while
else	is	with
except	lambda	yield

脚本注释

JKS 支持单行注释，不支持多行注释。

单行注释采用 # 开头，注释可以在语句或表达式行末。

示例:

# the first comment
str = "Hello, World!"  # the second comment

语句

JKS 仅支持单行语句。

不支持一行语句拆分到多行书写，也不支持一行中书写多条语句。

基本类型

JKS 提供标量、字符串与数组三种基本类型数据支持。

在数组的基础上，用户可以使用预定义的系统变量。

标量

JKS 不区分布尔类型、整形与浮点型数据。

对布尔类型，false对应0，true对应1。

示例:

var = 1
# or
var = 1.0
# or
var = (expr1 > expr2)

字符串

用户定义字符串时需要使用英文双引号 ("") 进行包裹 。

目前 JKS 支持的转义字符如下表，用户在定义字符串时需要注意，否则会造成解析错误。

转义字符	描述
\\	反斜杠符号
\’	单引号
\”	双引号
\n	换行
\t	横向制表符
\r	回车

示例:

string =  "this is a \"string\""
string =  "This is a string \n"

数组

数组是存放一组相同数据类型数据的容器。

目前仅支持标量类型的数据，不支持字符串数组或数组的嵌套。

• 数组定义

  • 语法形式：

  arr = [...]  #定义一个数组
  arr = []     #定义一个空数组
  

• 单元素的负索引访问

假设数组变量array的长度为N，对于单个元素的访问，支持形式：array[index]。

元素的索引支持负值，即index 范围支持 [-N, N-1]。

当index为非负值时，元素访问满足以下关系：

array[index] = array[-N+index]

当index取值不在支持范围内，则报错数组访问越界并终止程序执行。

示例：

a = [1,2,3,4,5,6,7,8,9,0]
b = a[-10] # b = a[0]
b = a[-11] # 报错数组访问超界

• 数组的子区间访问

支持访问指定数组的区间内指定间隔的子序列，并以数组形式返回。

对数组子区间的访问，具体格式为: array[startIndx:endIndex:step]

当step为0时，程序报错，并会终止程序执行；

其他情况下，即使startIndex，endIndex，step不满足逻辑条件时不会报错（超过数组边界），仅在指定数组有效的范围内返回满足条件的值，如不存在则返回空数组。

提供一种Step为1的子区间访问的特殊形式，即Step参数省略：array[startIndex，endIndex]

示例：

a = [1,2,3,4,5,6,7,8,9,0]
b = a[0:5]        #[1, 2, 3, 4, 5]
b = a[-5:10:1]    #[6, 7, 8, 9, 0]

• 数组与位姿表示

在 JKS 中，采用6元素数组表示机器人关节位置或空间位姿，长度单位为mm，角度单位为°。

示例：

endPosJ = [90,90,90,90,90,90] #关节空间位置数组
endPosL = [663.5,8.159996,6.950005,90,0,0] #笛卡尔空间位置数组

系统变量

在作业程序中定义的变量在程序执行结束之后将被释放。

对于希望值能够持久保存的变量，JKS提供系统变量机制。

系统可在程序中直接使用，在程序中修改值后退出或关机后，其值仍然可以保留。

系统变量只支持标量类型，目前支持用户使用的系统变量最多为100个，其访问方式如下：

sysvar[id], 其中id∈[5500, 5599]

示例：

sysvar[5500] = 100
a = sysvar[5500]

提示：

系统变量暂不支持负索引与区间访问。

表达式

算术运算符

算术运算符用来进行四则运算，按照运算符优先级将其分组，（*、/、%、**）的优先级高于（+、-）。

优先级高的运算符比优先级低的运算符结合得更加紧密，下表的运算符满足左结合律，即当运算符优先级相同时按照从左向右的顺序进行。

运算符	功能	用法
*	乘法	expr * expr
/	除法	expr / expr
%	求余	expr % expr
**	求幂	expr ** expr
+	加法	expr + expr
-	减法	expr - expr

逻辑与关系运算符

关系运算符作用于算术类型，逻辑运算符作用于任意能转换成布尔值的类型。

逻辑运算符和关系运算符的返回值类型都是布尔类型。

结合律	运算符	功能	用法	支持的输入数据类型
右	！	逻辑非	！expr	整型
左	&&	逻辑与	expr && expr	整型
左	II	逻辑或	expr II expr	整型
左	<	小于	expr < expr	整型、字符串
左	>	大于	expr > expr	整型、字符串
左	==	等于	expr == expr	整型、字符串、数组
左	!=	不等于	expr != expr	整型、字符串、数组
左	<=	小于等于	expr <= expr	整型、字符串
左	>=	大于等于	expr >= expr	整型、字符串

位运算符

位运算符作用于整数类型的运算对象，并把运算对象看作是二进制位的集合，目前仅支持异或操作。

位运算符(左结合律)：

运算符	功能	用法
^	异或	expr ^ expr

语句

通常情况下，语句是顺序执行的。

但除非是最简单的程序，否则仅有顺序执行远远不够，因此 JKS 提供了一组控制流语句以支持更复杂的执行控制。

简单语句

JKS 中，要求语句单独成行，且大多数语句无需结束符。

简单语句包括表达式语句、函数调用语句等。

条件语句

• if...end语句

if语句的作用是：判断一个指定的条件是否为真，根据判断结果决定是否执行另外一条语句。

if语句包括两种形式，一种含有else分支，另外一种没有。

语法形式如下：

if(condition):
    statement
end

示例：

condition = get_digital_output(0,1)
if(condition):
    endPosJ = [0,0,0,0,0,0]
    movj(endPosJ,0,60,200,0)
end

• if...else...end语句

语法形式如下：

if(condition):
    statement
else:
    statement
end

示例：

condition =  get_digital_output(0,1)
if(condition):
    endPosJ = [0,0,0,0,0,0]
    movj(endPosJ,0,60,200,0)
else:
    endPosL = [663.5,8.159996,6.950,90,0,0]
    movl(endPosL,0,250,250,0)
end

• if...elif...else...end语句

语法形式如下：

if(condition1):
    statement
elif(condition2):
    statement
else:
    statement
end

示例：

condition =  get_digital_output(0,1)
if(condition):
    endPosJ1 = [0,0,0,0,0,0]
    movj(endPosJ,0,60,200,0)
elif(condition):
    endPosJ2 = [90,90,90,90,-90,0]
    movj2(endPosJ,0,10,600,0)
else:
    endPosL = [663.5,8.159996,6.950,90,0,0]
    movl(endPosL,0,250,250,0)
end

循环语句

• while循环语句

只要条件为真，while语句就会重复地执行循环体。

语法形式如下：

while(condition):
    statement
end

在while结构中，只要condition的求值结果为真，就会一直执行 statement (通常是一个语法块)，condition不能为空。

如果condition第一次求值就是false，statement一次都不执行。

示例：

i = 0
while(i <= 4):
    endPosJ1 =[0,90,90,90,-90,0]
    movj(endPosJ1,0,10,600,0)
    endPosJ2 =[90,90,90,90,-90,0]
    movj(endPosJ2,0,10,600,0)
    i = (i+1)
end

跳转语句

跳转语句可以中断当前的while语句的执行过程， JKS 提供了两种跳转语句：break 和 continue 。

• break语句

break 语句负责终止离它最近的 while 语句，并从这些语句之后的第一条语句开始继续执行。

break 的作用范围仅限于最近的 while 循环。

示例： statement是语句块，condition1和condition2是判断条件

while(condition1):
statement
...
if(condition2):
    break
end
...
    statement
end

• continue语句

continue 语句终止最近的循环中的当前迭代并立即开始下一次迭代。

continue 语句只能出现在 while 循体的内部。

和 break 类似， continue 的作用范围仅限于最近的 while 循环。

continue 中断当前的代，但是会继续执行当前的循环，对于 while 语句来说即继续判断条件的值。

示例：

statement是语句块，condition1和condition2是判断条件。

while(condition1):
    statement
    ...
    if(condition2):
        continue
    end
    ...
    statement
end

多线程

最新的控制器软件支持多线程功能，用户可以在非主线程中使用特定的非运动相关类指令。

线程的创建

用户使用多线程时，需要通过子程序文件的方式定义线程的执行体，即线程执行体被单独保存在以 JKS 为后缀的脚本文件中。

线程创建时需指定线程执行体子程序文件的绝对路径，线程创建后将自动开始执行。

JAKA控制器支持子线程数量为5个。

线程创建时需要同步写入线程名称，线程的名称用于对子线程资源的管理，如线程的销毁、同步、暂停等操作。

示例： /path/to/thread/file. JKS 为子线程对应脚本文件的绝对路径，thread_name为标识该线程的唯一字符串。

create_thread(“/path/to/thread/file. JKS ”, “thread_name”)

线程的操作

JKS支持线程等待（join）与线程销毁操作，不支持线程分离（detach）。

主线程结束后所有的子线程均将被终止，所使用的资源也将会被回收。

线程的相关操作仅支持在主线程中调用，在子线程中调用无效；线程操作中必须保证是有效的线程名称，无效的线程名称将导致运行时错误。

运动相关类、部分设置类（如：负载设置，坐标系设置）指令只能在主线程中使用，在子线程中这些指令将会被跳过，不会被执行。

示例：
thread_name为线程名称

线程同步：
thread_join("thread_name")
线程销毁：
thread_destroy("thread_name")

此外子线程与主线程可以调用程序暂停指令，暂停指令执行后程序中所有的线程都将进入暂停状态；程序恢复将恢复所有线程继续运行。

线程的调度

用户在作业程序中创建的所有子线程保持相同的优先级，且不支持修改。

在控制指令周期内仅允许一个线程拥有底层控制接口调用权，各线程之间需要通过竞争实现。

在竞争的过程中，线程其他的任务也将被阻塞运行。

线程的互斥

多个线程同时访问共享数据或资源（如系统变量）时可能会冲突， JKS 提供进入和退出临界区域的操作接口以解决资源冲突。

在多个线程同时准备进入该临界区域时，只有一个线程能获得该临界区域的操作权限，其他所有的线程将处于等待状态，直到线程退出临界区域。

由于进入临界区域相当于独占运行权限，为保证其他线程能够正常运行，要求在进入与退出临界区域期间执行的指令尽量简短。

示例：

thread_enter_critical()

# do some stuff

thread_exit_critical()

脚本预置函数

运动相关指令

基本运动

movel

指令原型：

movl(var_pos, rel_flag, vel, acc, tol, end_cond, ori_vel, ori_acc, planner_type)

指令说明：

用于控制机器人执行笛卡尔空间直线运动。

参数介绍：

var_pos	六元素数组变量，用于指定笛卡尔空间目标位置，需提前定义。
rel_flag	指定该段运动是相对运动还是绝对运动。 ·0为绝对运动，此时var_pos给定值将被解释为笛卡尔空间某绝对位置； ·1为相对当前用户坐标系的增量运动，此时var_pos给定值将被解释为笛卡尔空间位置增量； ·2为相对当前工具坐标系的增量运动。
vel	运动速度，单位mm/s。
acc	直线加速度，单位mm/ s^2。
tol	到达指定终点的容许偏差。 若为0，则将准确到达目标点； 若为正值，则位置可能会与后续段混合，不能准确到达目标点。
end_cond	该段指令停止条件，可选参数为一个包括3个参数的数组，包括： di_type：输入类型。 ·-1表示不适用 ·0表示basic IO ·1表示工具IO ·2表示扩展IO ·3表示保留 ·4表示Modbus IO ·5表示Profinet IO ·6表示Ethernet/IP IO di_index: IO 地址。 di_state: IO 满足条件的状态0/1。
ori_vel	姿态速度，是可选参数，单位deg/s。 不输入该参数的话，机器人将采用最大姿态速度运行。
ori_acc	姿态加速度，是可选参数，单位deg/s^2。 不输入该参数的话，机器人将采用最大姿态加速度运动。
planner_type	速度规划类型，根据不同的场景灵活选择。 0: 采用节拍优先的速度规划方式； 1: 采用柔顺优先的速度规划方式。

返回值：

无

movej

指令原型：

movj(var_pos, rel_flag, vel, acc, tol, end_cond, planner_type)

指令说明：

用于控制机器人执行关节空间运动。

参数介绍：

var_pos	六元素数组变量，用于指定关节空间目标位置，需提前定义。
rel_flag	指定该段运动是相对运动还是绝对运动。 ·0为绝对运动，此时var_pos给定值将被解释为关节空间某绝对位置； ·1为相对运动，此时var_pos给定值将被解释为关节空间位置增量。
vel	各关节指令速度，单位deg/s。 实际运动时，将受各关节实际最大速度约束。
acc	直线加速度，单位: deg/ s^2。
tol	到达指定终点的容许偏差。 若为0，则将准确到达目标点； 若为正值，则可能会与后续段混合，不能准确到达目标点。
end_cond	该段指令停止条件，可选参数为一个包括3个参数的数组，包括： di_type：输入类型。 ·-1表示不适用 ·0表示basic IO ·1表示工具IO ·2表示扩展IO ·3表示保留 ·4表示Modbus IO ·5表示Profinet IO ·6表示Ethernet/IP IO di_index: IO 地址。 di_state: IO 满足条件的状态0/1。
planner_type	速度规划类型，根据不同的场景灵活选择。 0: 采用节拍优先的速度规划方式； 1: 采用柔顺优先的速度规划方式。

返回值： 无

movec

指令原型：

movc(var_pos_mid, var_pos_end, rel_flag, vel, acc, tol, turn_cnt, end_cond, movc_mode, planner_type)

指令说明：

用于控制机器人执行笛卡尔空间圆弧运动。

参数介绍：

var_pos_mid	六元素数组变量，用于指定空间圆弧的中间经过点，需提前定义。
var_pos_end	六元素数组变量，用于指定空间圆弧的停止点，需提前定义。
rel_flag	指定该段运动是相对运动还是绝对运动，目前仅支持绝对运动。 ·0为绝对运动，此时var_pos给定值将被解释为笛卡尔空间某绝对位置。
vel	各关节指令速度，单位deg/s。 实际运动时，将受各关节实际最大速度约束。
acc	用于指定运动的加速度，单位mm/s^2。
tol	到达指定终点的容许偏差。 若为0，则将准确到达目标点； 若为正值，则可能会与后续段混合，不能准确到达目标点。
turn_cnt	用户指定圆弧运动圈数（非负实数），可选参数。 当圈数为0时，则按三点确定圆弧运动； 如果圈数为非0，则按三点确定的圆弧运动指定圈数，姿态保持初始点姿态与转轴的夹角相同。
end_cond	该段指令停止条件，可选参数。但在1.7.1_28及之后版本若需要控制圆弧中间姿态时，为必选参数。是一个包括3个参数的数组，包括： di_type：输入类型。 ·-1 表示不适用 ·0 表示basic IO ·1表示工具IO ·2表示扩展IO ·3保留 ·4表示ModbusIO ·5表示Profinet IO ·6表示Ethernet/IP IO di_index: IO 地址。 di_state: IO 满足条件的状态0/1。
movc_mode	指定姿态在圆弧运动中的模式，为可选参数，当turn_cnt为0时生效。 ·0为最小姿态变化模式，机器人的姿态将绕起始-终止姿态转轴以最小角度变化方向运动； ·1为较大姿态变化模式，机器人的姿态将绕起始-终止姿态转轴较大角度变化方向（即最小角度变化方向的反方向）运动； ·2 为中间点姿态适配模式，机器人的姿态将根据中间点姿态自动选择最小姿态变换或较大姿态变化； ·3 为姿态夹角固定模式，机器人圆弧运动中的工具姿态与笛卡尔圆弧轴线-半径所构成坐标系的变换夹角固定。
planner_type	单条运动指令速度规划类型，根据不同的场景灵活选择。 0: 采用节拍优先的速度规划方式； 1: 采用柔顺优先的速度规划方式。

返回值：

无

get_atl_joint_pose

指令原型：

atlJntPos = get_atl_joint_pose() 

指令说明：

用于获取当前机器人实际关节位置。

返回值：

返回当前实际关节位置。

get_atl_tcp_pose

指令原型：

atlTcpPos = get_atl_tcp_pose()

指令说明：

用于获取当前机器人实际末端工具中心点位姿。

返回值：

返回当前实际工具末端中心点位姿。

get_atl_flange_pose

指令原型：

atlFlangePos = get_atl_flange_pose()

指令说明：

用于获取当前机器人末端法兰中心点位姿。

返回值：

返回当前实际末端法兰中心点位姿。

enable_speed_override

指令原型：

enable_speed_override(type, vel, acc)

指令说明：

用于设置函数块的速度与加速度。

参数介绍：

type	·0表示笛卡尔空间运动类型 ·1表示关节空间运动类型
vel	double类型数据，表示设置的覆盖速度。
acc	double类型数据，表示设置的覆盖加速度。

返回值：

无

disable_speed_override

指令原型：

disable_speed_override(type)

指令说明：

用于取消函数块的速度与加速度设置。

参数介绍：

type	·0表示笛卡尔空间运动类型 ·1表示关节空间运动类型

返回值：

无

enable_planner_override()

指令原型：

enable_planner_override(type)

指令说明：

用于设置全局速度规划器类型。

参数介绍：

type	全局速度规划类型，根据不同的场景灵活选择。 0: 采用节拍优先的速度规划方式； 1: 采用柔顺优先的速度规划方式。 使用全局速度规划指令时，单条指令中的速度规划参数将会失效。

返回值：

无

disable_planner_override

指令原型：

disable_planner_override()

指令说明：

用于取消全局速度规划器类型的设置。

返回值：

无

传送带跟踪

enable_conveyor_linear_track

指令原型：

enable_conveyor_linear_track(dir, mm_per_pulse, trigger, com_dis, max_dis)

指令说明：

用于使能直线传送带跟踪。

参数介绍：

dir	跟踪方向，可以为X+, Y+, Z+, X-, Y-, Z-中的任意一个。
mm_per_pulse	用于指定脉冲当量，即跟踪传送带上的编码器反馈每个脉冲对应传送带方向的位移，单位为mm。
trigger	可选参数，为机器人运动起始点到开始跟踪传送带之间的距离。用于自定义机器人开始跟踪传送带的位置，范围为0~3000 mm。
com_dis	用于补偿实际位置与示教位置之间的误差，范围为±100 mm。
max_dis	可选参数，为机器人运动起始点到运动终点之间的距离。用于限制机器人跟踪距离，避免机器人超出传送带范围或达到奇异点，范围为1~3000 mm。

返回值：

无

enable_conveyor_circular_track

指令原型：

enable_conveyor_circular_track(convey_P1, convey_P2, convey_P3, rad_per_pulse, rotate_tool, com_dis,  max_dis)

指令说明：

用于使能圆形传送带跟踪。

参数介绍：

convey_P1 convey_P2 convey_P3	表示世界坐标系下一点的位置向量，例如： convey_P1 = [P1x, P1y, P1z] convey_P2 = [P2x, P2y, P2z] convey_P3 = [P3x, P3y, P3z] convey_P1, convey_P2, convey_P3为传送带上共圆三点在世界坐标系下的位置坐标，在传送带转动方向依次选取，用于获取传送带圆心坐标系{O}在世界坐标系下的变换矩阵，可通过直接输入或示教得到。
rad_per_pulse	用于指定脉冲当量，指跟踪传送带的编码器每反馈一个脉冲对应地在Oz轴正方向（右手定则）上旋转的角度，单位为°/cnt。
rotate_tool	·0圆形传送带跟踪过程中末端姿态保持不变 ·1末端绕传送带轴线转动，姿态改变（App默认为1）
com_dis	用于补偿实际位置与示教位置之间的误差，范围为±20° 。
max_dis	可选参数，为机器人运动起始点到运动终点之间的距离。用于限制机器人跟踪距离，避免机器人超出传送带范围或达到奇异点，范围为1~360° 。

返回值：

无

disable_convayor_track

指令原型：

disable_convayor_track()

指令说明：

用于关闭传送带跟踪。

返回值：

无

record_pulse_cond()

指令原型：

record_pulse_cond(type, index, state)

指令说明：

用于获取并存储传送带上的物料位置，与IO绑定，防止因传送带运动速度较快，机器人来不及处理每一个物料而漏料。此指令需要与“传送带队列取值”搭配使用。

使用此指令后，传送带上触发IO的物料位置信息被记录在控制器内，当程序运行“传送带队列取值”指令后，存储的物料位置信息按存储的先后顺序被获取。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	所控制数字输出的编号，从0开始索引。
state	·1为开 ·0为关

返回值：

无

get_pulse_cond()

**指令原型：**

get_pulse_cond()

指令说明：

用于获取存储的传送带脉冲队列信息

返回值：

无

clear_pulse_cond()

指令原型：

clear_pulse_cond()

指令说明：

用于清空存储的传送带脉冲队列信息

返回值：

无

record_pos_cond()

指令原型：

record_cond(array)

指令说明：

用于存储位姿数组变量队列，可搭配传送带视觉跟随使用，存储相机发送的位姿信息

参数介绍：

array	位置变量或程序变量，1-12位数组均可。

返回值：

无

get_pos_cond()

指令原型：

get_pos_cond()

指令说明：

用于获取存储的位姿队列信息

返回值：

从位姿队列中获取到的位姿数组变量

clear_pos_cond()

指令原型：

clear_pos_cond()

指令说明：

用于清空存储的位姿队列信息

返回值：

无

get_pulse_num()

指令原型：

get_pulse_num()

指令说明：

用于获取当前传送带脉冲队列所存储目标的个数

返回值：

当前传送带脉冲队列所存储目标的个数

get_pos_num()

指令原型：

get_pos_num()

指令说明：

用于获取当前位姿队列所存储目标的个数

返回值：

当前位姿队列所存储目标的个数

运动柔顺控制

set_compliance_ft_config

指令原型：

set_compliance_ft_config(id, admitctrlconfig, immed)

指令说明：

用于恒力柔顺控制配置。admitctrlconfig是配置参数数组。

参数介绍：

id	代表配置轴编号[0, 5]
admitctrlconfig	= [opt, FTuser, FTreboundK, FTconstant, FTnormalTrack] opt：在该方向（由id参数指定的轴方向）上是否开启恒力柔顺，1代表开启，0代表不开启。 FTuser：机器人在恒力柔顺控制过程中所表现出的刚度，一般力方向上需要设置大于5，力矩方向上设置大于0.2。 FTreboundK：机器人外力作用下，偏离原位置后产生向原位置反弹的运动趋势时所表现出的弹性系数。需要设置为非负数，其中设置为0代表不进行反弹。 FTconstant：代表目标恒力。 FTnormalTrack：内部预留参数，必须给定固定数值0。
immed	内部预留参数，必须给定固定数值1。

返回值：

无

set_compliance_velocity_level

指令原型：

velCompliantCtrl = [level, rate1, rate2, rate3, rate4]

set_compliance_velocity_level(velCompliantCtrl)

指令说明：

用于设置速度柔顺控制阶梯速度。

参数介绍：

velCompliantCtrl	在速度模式下，当机器人末端受力大于控制器设定值时，机器人会按照设定的倍率进行减速，直至传感器检测值小于控制力设定值。 速度柔顺控制阶梯速度分三个等级，并且1 > rate1 > rate2 > rate3 > rate4 > 0 ·等级为1时，只能设置rate1，rate2两个等级，rate3，rate4的值为0 ·等级为2时，只能设置rate1，rate2，rate3 三个等级，rate4的值为0 ·等级为3时，能设置 rate1，rate2，rate3，rate4四个等级

返回值：

无

set_compliance_condition

指令原型：

compliantCondition = [fx, fy, fz, tx, ty, tz]

set_compliance_condition(compliantCondition)

指令说明：

用于设置速度柔顺控制力。

参数介绍：

compliantCondition	用于设置力和力矩的停止条件。 当机器人的实际力大于这个条件的时候，机器人开始按set_compliance_velocity_level设定的倍率减速。 fx, fy, fz, tx, ty, tz的范围：大于0。

返回值：

无

disable_force_control

指令原型：

disable_force_control()

指令说明：

用于关闭力控。

返回值：

无

enable_force_control

指令原型：

enable_force_control(type, compensation)

指令说明：

用于柔顺控制类型配置和传感器补偿。

参数介绍：

type	·0 代表不使用任何一种柔顺控制 ·1 代表恒力柔顺控制 ·2 代表速度柔顺控制
compensation	·1 代表开启柔顺控制前进行一次传感器校零 ·0 代表开启柔顺控制前不进行传感器校零

返回值：

无

set_end_force_condition

指令原型：

condition = [enableEndCond, lowFlag, lowLimitForce, upFlag, upLimitForce]

set_end_force_condition(axis, condition)

指令说明：

用于设置力控终止条件。设置力控终止条件，不能立即生效，默认是非即时指令，作用且仅作用于其后的第一条运动指令。此终止条件触发时，该运动指令将被立刻终止，程序跳转至该运动指令的下一行继续执行。

参数介绍：

axis	代表轴号，取值范围是[0, 5]
enableEndCond	是否使能，1代表生效，0则相反
lowFlag	运动终止力下限生效标志位，1代表生效，0则相反
lowLimitForce	运动终止力下限
upFlag	运动终止力上限生效标志位，1代表生效，0则相反
upLimitForce	运动终止力上限

返回值：

无

set_force_control_frame

指令原型：

set_force_control_frame(ftFrame)

指令说明：

该函数用于设置力控坐标系。

参数介绍：

ftFrame	·0 表示工具坐标系 ·1 代表世界坐标系

返回值：

无

get_sensor_torque

指令原型：

torq = get_sensor_torque(type)

指令说明：

用于获取力矩底座或末端力矩传感器的力矩值，该值为补偿传感器末端负载后的净力矩值。

参数介绍：

type	·0为末端力矩传感器 ·其他值保留

返回值：

六维数组表示的六维力矩传感器读数

torque_sensor_enable

指令原型：

torque_sensor_enable(enable)

指令说明：

开启末端力传感器。

参数介绍：

enable	·0为关闭 ·1为开启

返回值：

无

set_force_sensor_zero

指令原型：

set_force_sensor_zero()

指令说明：

末端力传感器校零。

参数介绍：

无

返回值：

无

接口设置与查询

IO控制与查询

set_digital_output

指令原型：

set_digital_output(type, index, tarState, immed)

指令说明：

用于控制数字输出信号。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	所控制数字输出的编号，从0开始索引。
tarState	·1为开 ·0为关
immed	·1为即时指令 ·0为非即时指令 若为非即时指令，则该指令的实际执行将在下一条运动指令之前执行。

注：

即时IO指令会打断不同运动段之间的转接，非即时仅限于控制柜DO/AO可用。

返回值：

无

set_analog_output

指令原型：

set_analog_output(type, index, tarValue, immed)

指令说明：

用于控制模拟输出信号。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	所控制模拟输出的编号，从0开始索引。
tarValue	Real类型值，用于指定模拟输出的目标值。
immed	·1为即时指令 ·0为非即时指令 若为非即时指令，则该指令的实际执行将在下一条运动指令之前执行。

注：

即时IO指令会打断不同运动段之间的转接。

返回值：

无

get_digital_output

指令原型：

get_digital_output(type, index)

指令说明：

用于获取指定数字输出的状态。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	数字输出索引

返回值：

函数返回查询结果：0 -> off, 1 -> on

get_analog_output

指令原型：

get_analog_output(type, index)

指令说明：

用于获取指定模拟输出的状态。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	模拟输出索引

返回值：

函数返回double类型的查询结果。

get_digital_input

指令原型：

get_digital_input(type, index)

指令说明：

获取指定数字输入的状态。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	数字输入索引

返回值：

函数返回查询结果：0 为关，1 为开。

get_analog_input

指令原型：

get_analog_input(type, index)

指令说明：

获取指定模拟输入的状态。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	模拟输入索引

返回值：

函数返回double类型的查询结果。

wait_input

指令原型：

wait_input(type, index, state, time)

指令说明：

用于等待指定输入变成指定状态，若超出最大等待时间，则置TIMEOUT状态标志，可用GETTIMEOUT函数查询。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	输入的索引
state	期待的输入状态
time	最长等待时间，0为无限等待（最长等待10000000000秒）

返回值：

无

get_timeout

指令原型：

get_timeout()

指令说明：

该函数用于获取wait_input指令的执行结果。

1为等待超时，0为在指定时间内成功等到该信号。

返回值：

无

set_motion_digital_output

指令原型：

set_motion_digital_output(type, index, refpoint, distance, tarState)

指令说明：

用于控制运动过程中输出数字信号。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	所控制数字输出的编号，从0开始索引。
refpoint	信号触发距离所选参考点 ·0为起始点 ·1为终止点
distance	信号触发距离。
tarState	·1为开 ·0为关

注：

运动中设置IO指令之后需要存在运动指令才生效。两段运动指令中间最多可设置8个运动中设置IO指令。

返回值：

无

set_motion_analog_output

指令原型：

set_motion_analog_output(type, index, refpoint, distance, tarValue)

指令说明：

用于控制运动过程中输出模拟信号。

参数介绍：

type	·0标准IO（控制柜） ·1工具IO ·2为扩展IO ·3保留 ·4为Modbus IO ·5为PROFINET IO ·6为Ethernet/IP IO
index	所控制模拟输出的编号，从0开始索引。
refpoint	信号触发距离所选参考点 ·0为起始点 ·1为终止点
distance	信号触发距离。
tarValue	Real类型值，用于指定模拟输出的目标值。

注：

运动中设置IO指令之后需要存在运动指令才生效。两段运动指令中间最多可设置8个运动中设置IO指令。

返回值：

无

TIO控制与查询

tio_update_signal

指令原型：

tio_update_signal(strId, freq)

指令说明：

用于以一定周期刷新指定的TIO Modbus RTU信号。

参数介绍：

strId	信号量的标识符
freq	为0时，仅刷新一次； 为其他正值时为刷新频率，刷新频率内部自动受限于CAN通讯瓶颈。

返回值：

无

tio_get_signal_value

指令原型：

res = tio_get_signal_value(strId)

指令说明：

用于获取指定信号的值。

参数介绍：

strId	信号量的标识符

返回值：

返回信号的值。

tio_send_command

指令原型：

tio_send_command(chnId, cmdBuf, crcType)

指令说明：

用于向指定的TIO RS485通道发送字节数据。

参数介绍：

chnId	通道编号。 ·0为RS485通道1 ·1为RS485通道2
cmdBuf	字节数组
crcType	发送数据类型，当且指定通道为RS485透传时生效，Modbus RTU时写0。

返回值：

无

网络通讯

socket_open

指令原型：

sockid = socket_open(ip, port)

指令说明：

用于打开指定的IP与端口号，并将创建的SOCKET句柄保存在变量并返回。

参数介绍：

ip	字符串形式TCP服务器地址，如“192.168.1.10”
port	TCP服务器端口

返回值：

返回socket句柄

socket_close

指令原型：

socket_close(sockid)

指令说明：

用于关闭指定的套接字。

参数介绍：

sockid	需要关闭的套接字连接

返回值：

无

socket_get_var

指令原型：

varname = socket_get_var(sockid, type, argname, timeout)

指令说明：

用于请求远端对参数的设置。

参数介绍：

sockid	套接字ID，需事先创建。
type	参数类型。 ·0为整型 ·1为浮点数 ·2为字符串
argname	字符串类型的变量名，表示想要获取的变量的值。 形式为argname或<argname>
timeout	获取反馈等待超时，0为永久等待（最长65536秒）。

返回值：

返回值储存变量。

该函数将通过socket发送字符串get <arg_varname>，并期望接收数据格式<arg_varname><value>。默认有2s的超时，超时后返回0。

当期望发送一个数组时，上位机发送格式为：

<arrName><{num1, num2, ..., numN}>

当期望发送一个字符串时，上位机发送格式为：

<strName><“stringValue”>

socket_read_real

指令原型：

res = socket_read_real(sockid, num, timeout)

指令说明：

用于通过制定的套接字从外界获取（一组）数，并存储在数组变量中。

参数介绍：

sockid	套接字ID，需事先创建。
num	期望接收的数的数量。
timeout	获取反馈等待超时，0为永久等待（最长65536秒）。

返回值：

接收的数据结果。

若接收失败，则返回标量0，成功接收则均存在数组中。

默认有2s的超时，若接收失败，将返回0。

socket_read_string

指令原型：

res = socket_read_string(sockid, prefix, suffix, timeout)

指令说明：

用于通过指定的套接字从外界获取一段字符串，并存储在变量中。

函数返送格式为get#string#prefix#suffix#，期望接收数据格式为prefixSTRINGsuffix。

参数介绍：

sockid	套接字ID，需事先创建。
prefix	期望接收字符串的前缀要求。
suffix	期望接收的字符串的后缀要求。
timeout	获取反馈等待超时，0为永久等待。

返回值：

接收的数据结果。

默认2s的超时，若接收失败，将返回空的字符串。

socket_send

指令原型：

res = socket_send(sockid, var)

指令说明：

用于通过指定的SOCKET以字符串形式发送一个变量的值。

参数介绍：

sockid	套接字ID，需事先创建。
var	期望发送的变量，变量目前支持Number，Number数组，以及 String类型。 发送数组时，发送的字符串格式为{Num1, Num2, ...}

返回值：

res>为发送结果标志。

默认有2s的发送超时，如果发送成功，返回1，否则返回0。

发送的数据格式为：

<varName><varValue>

<intVar><12>

<strVar><“string”>

<listVar><{ele1, ele2, ele3, ...}>

socket_recv

指令原型：

res = socket_recv(sockid, timeout)

指令说明：

用于从指定的socket接收数据，用户可设置超时时间。

注：

该指令单纯用于接收数据，不会向另一连接端发送请求。

参数介绍：

sockid	套接字ID，需事先创建。
timeout	接收超时设置。

返回值：

正常接收，函数返回接收的字符串。

如果超时未接收到数据，返回为空字符串；

如果网络问题，则会返回标量-1。

参数设置与查询

set_payload

指令原型：

set_payload(m, centriod)

指令说明：

用于设置当前机器人负载。

参数介绍：

m	负载质量，单位kg。
centroid	负载质心，包含三个分量的数组，单位：mm。

注：

该指令会同步运动，打断转接。

返回值：

无

get_payload

指令原型：

payload = get_payload()

指令说明：

用于获取当前机器人负载。

返回值：

返回机器人法兰末端总负载。

payload[0]为负载质量（单位kg），payload[1]~[3]为负载质心（单位mm）。

set_collision_level

指令原型：

set_collision_level(clsnLevel)

指令说明：

默认不支持该指令；

若执行的JKS程序包含该指令，主线程在解析到该指令时会报错提示，并跳过该指令、继续执行后续的指令；

子线程解析到该指令时会直接跳过，继续执行后续指令（子线程中不处理运动及修改运动参数的指令）。

get_collision_level

指令原型：

res = get_collision_level()

指令说明：

用于获取当前碰撞检测灵敏度。

返回值：

返回当前碰撞灵敏度。

set_tool

指令原型：

set_tool(var_tool)

指令说明：

用于设置工具末端相对于末端法兰的位置偏置。

法兰坐标系垂直端面向外为z轴正方向， 工具IO连接端口为y轴负方向。

参数介绍：

var_tool	工具末端相对于法兰坐标系的偏置，为6元素数组。

返回值：

无

set_tool_id

指令原型：

set_tool_id(id)

指令说明：

用于设置工具坐标系id。

参数介绍：

id	取值[0, 15]。 控制系统内最大支持16个工具，通过设置ID指定当前使用的工具偏置值。当id为0时，即使用默认工具坐标系与法兰坐标系重合。

返回值：

无

get_tool_offsets

指令原型：

res = get_tool_offsets()

指令说明：

用于获取当前工具坐标系偏置值。

返回值：

返回6元素数组。

get_tool_offsets_of

指令原型：

res = get_tool_offsets_of(id)

指令说明：

用于获取指定工具坐标系偏置值。

参数介绍：

id	指定的工具坐标系，取值范围是[1, 15]。

返回值：

返回6元素数组。

set_user_frame

指令原型：

set_user_frame(user_frame)

指令说明：

用于设置用户坐标系。

设置时工具ID将设置为-1，程序中设置后不会被保存。

参数介绍：

user_frame	用户坐标系值，为6元素数组。

返回值：

无

set_user_frame_id

指令原型：

set_user_frame_id(id)

指令说明：

用于设置用户坐标系id。

参数介绍：

id	取值[0, 15]。 控制系统内最大支持16个用户坐标系，通过设置ID指定当前使用的用户坐标系偏置值。当id为0时，即不使用用户自定义的坐标系，而是默认的世界坐标系。

返回值：

无

get_user_frame

指令原型：

res = get_user_frame()

指令说明：

用于获取当前用户坐标系偏置值。

返回值：

返回6元素数组。

get_user_frame_of

指令原型：

res = get_user_frame_of(id)

指令说明：

用于获取指定用户坐标系偏置值。

参数介绍：

id	指定的用户坐标系，取值范围是[1, 15]。

返回值：

返回6元素数组。

辅助函数库

数学计算库

函数原型	函数描述
res = atan2(arg_y, arg_x)	arg_y/arg_x 的反正切，返回值单位为°
res = abs(arg)	计算表达式绝对值
res = acos(arg)	反余弦函数，返回值单位为°
res = asin(arg)	反正弦函数，返回值单位为°
res = cos(arg)	余弦函数，参数单位为°
res = sin(arg)	正弦函数，参数单位为°
res = tan(arg)	正切函数，参数单位为°
res = floor(arg)	向下取整
res = ceil(arg)	向上取整
res = round(arg)	四舍五入取整
res = sqrt(arg)	取平方根
res = rad2deg(arg)	弧度转角度
res = deg2rad(arg)	角度转弧度

位姿运算库

pose_add

指令原型：

res = pose_add(pos1, pos2)

指令说明：

用于计算两个位姿之和并返回计算结果。

位置进行简单累加计算；

姿态计算公式为：R_res = R_pos2 * R_pos1

注：

R表示旋转矩阵。

返回值：

返回计算结果。

pose_sub

指令原型：

res = pose_sub(pos1, pos2)

指令说明：

用于计算两个位姿之差并返回计算结果。

位置进行简单相减计算；

姿态计算公式为：R_res = inv(R_pos2) * R_pos1

注：

R表示旋转矩阵。

返回值：

返回计算结果。

pose_dist

指令原型：

res = pose_dist(pos1, pos2)

指令说明：

用于计算两个位姿之间的距离，计算仅考虑位置坐标。

返回值：

返回计算结果。

pose_inv

指令原型：

res = pose_inv(pos)

指令说明：

用于计算某个位置的逆变换。

返回值：

返回pose形式的计算结果。

pose_trans

指令原型：

res = pose_trans(p_from, p_from_to)

指令说明：

用于计算位置变换。

计算公式为：p_res = p_from * p_from_to

返回值：

返回位置结果。

pose_intpl

指令原型：

res = pose_intpl(pos1, pos2, alpha)

指令说明：

用于按照给定的系数计算两点之间的插补点。

计算公式为：p_res = pos1 + (pos2 - pos1) * alpha

其中，alpha >= 0 且 alpha <= 1，包含姿态且其插值方法同为线性插值。

返回值：

返回插补点的位置变量。

xy_plane_trans

指令原型：

res = xy_plane_trans(posebase, dx, dy, drz)

指令说明：

该指令将刚体在XY平面内做变换，在posebase处先绕Z轴旋转drz度，然后沿X轴平移dx，沿Y轴平移dy。

返回值：

返回变换后的位姿。

yz_plane_trans

指令原型：

res = yz_plane_trans(posebase, dy, dz, drx)

指令说明：

该指令将刚体在YZ平面内做变换，在posebase处先绕X轴旋转drx度，然后沿Y轴平移dy，沿Z轴平移dz。

返回值：

返回变换后的位姿。

zx_plane_trans

指令原型：

res = zx_plane_trans(posebase, dz, dx, dry)

指令说明：

该指令将刚体在ZX平面内做变换，在posebase处先绕Y轴旋转dry度，然后沿Z轴平移dz，沿X轴平移dx。

返回值：

返回变换后的位姿。

kine_inverse

指令原型：

res = kine_inverse(posJ, posP)

指令说明：

该指令用于计算运动学逆解。

功能为计算输入的笛卡尔空间位置posP所对应的关节空间位置。

posJ为这个逆解关节值附近的一组关节值，用来确定逆解函数多解的选取。

返回值：

返回逆运动学计算结果。

当逆解失败时，程序报错终止。

kine_forward

指令原型：

res = kine_forward(posJ)

指令说明：

用于计算运动学正解。

功能为计算输入的关节角度的所在笛卡尔空间位置。

返回值：

返回正运动学计算结果。

is_pose_reachable

指令原型：

res = is_pose_reachable(posP)

指令说明：

用于判断在当前位姿下，是否能够以通过笛卡尔空间运动指令运动至posP。

返回值：

若可以，则返回1（条件为真）；

若否，则返回0（条件为假）。

字符串操作库

sprintf

指令原型：

resLen = sprint(bufferOut, stringFormat, …)

指令说明：

用于对字符串的格式化输出，即将指定数据按指定格式输出为字符串。

参数介绍：

bufferOut	格式化后的字符串结果，变量需事先定义。
stringFormat	定义格式字符串，目前仅支持变量形式。 支持对%f、%d、%s三种类型变量的格式化。 格式如：%f、%s、%d
…	待格式化变量，可变参数。支持整型、浮点型及字符串类型的变量，或者常数。

返回值：

strLen：如果格式化成功，返回字符串的长度，否则返回-1。

sscanf

指令原型：

resNum = sscanf(bufferIn, stringFormat, …)

指令说明：

用于对字符串的格式化输入，即将匹配一定格式的字符串将数据输入到变量中。

参数介绍：

bufferIn	待匹配的字符串，目前仅支持变量格式。
stringFormat	定义格式字符串，目前仅支持变量形式。 支持对%f、%d、%s三种类型变量的格式化。 格式如：%f、%d、%s %f 匹配一个浮点数； %d 匹配十进制整数，数字前面的+或-可选； %s 匹配字符串，读取连续字符直到遇到一个空格字符（空白、换行和制表符等）或格式化字符串中下一个匹配字符（非%s、%f、%d）。
…	待格式化变量，可变参数。支持整型、浮点型及字符串类型的变量，或者常数。

返回值：

resNum：如果格式化成功，返回匹配的变量的数目，否则返回-1。

string_concat

指令原型：

strRes = string_concat(str1, str2)

指令说明：

用于两个字符串的拼接，并返回拼接后的字符串。

参数介绍：

str1	待拼接的子字符串，变量或者常量。
str2	待拼接的子字符串，变量或者常量。

返回值：

strRes: 字符串拼接结果。

get_string_from_array

指令原型：

resLen = get_string_from_array(arrayIn, splittingToken, stringOut)

指令说明：

用于将满足一定格式的字符串转为数组变量。

参数介绍：

arrayIn	用户给定的数组。
splittingToken	字符串格式的分隔符。
stringOut	转换成功后的字符串。

返回值：

resLen: 如果转换成功，返回字符串的长度（不包含截止符）；失败则返回-1。

get_array_from_string

指令原型：

resNum = get_array_from_string(stringIn, splittingToken, arrayOut)

指令说明：

用于将给定字符串转换为数组变量。

参数介绍：

stringIn	用户给定的字符串（包含个数组中的数据）。
splittingToken	字符串格式的分隔符。
arrayOut	转换成功后的数组。

返回值：

resNum: 如果转换成功，返回数组的元素数量；失败则返回-1。

get_length

指令原型：

len = get_length(str_or_arr)

指令说明：

用于获取字符串或数组的长度。

返回值：

如果参数数据类型不是数组或字符串，返回-1，不报错，程序继续正常执行。

示例：

len = get_length(int_val)

参数int_val是一个整型变量，则指令执行的结果为len = -1。

strcmp

指令原型：

res = strcmp(str1, str2)

指令说明：

用于两个字符串间的比较。

返回值：

若str1=str2，则返回零；

若str1<str2，则返回负数；

若str1>str2，则返回正数。

程序控制与调试

log_message

指令原型：

log_message(level, message)

指令说明：

用于用户自行添加日志信息。

参数介绍：

level	日志消息类型。 具体定义如下： ·INFO:1 ·WARNING:2 ·ERROR:3
message	日志消息文本。 不支持Unicode类型。

返回值：

无

get_system_clock

指令原型：

clock = get_system_clock()

指令说明：

用于用户获取系统实时时钟。

返回值：

为double类型浮点数，单位为ms（毫秒），精确到ns。

底层使用CLOCK_MONOTONIC，即本次系统启动后流逝的时钟数。

sleep

指令原型：

sleep(time)

指令说明：

用于延时程序的一段执行时间。

参数介绍：

time	延长时间长度，单位s。

注：

该指令会打断不同运动段之间的转接。

返回值：

无

pause

指令原型：

pause()

指令说明：

用于程序暂停操作，程序中调用该指令时，所有线程都将暂停。

返回值：

无

exit

指令原型：

exit()

指令说明：

用于控制作业程序终止。

返回值：

无

多线程指令

create_thread

指令原型：

create_thread(thread_file_path, thread_name)

指令说明：

用于创建子线程，并启动线程运行。

参数介绍：

thread_file_path	线程程序文件保存的绝对路径。 必须统一保存在/user/etc/jkzuc/scripts/program/下，其他前置路径都不可行。
thread_name	线程辨识唯一字符串，不支持Unicode。 线程名称重复会提示创建失败。

返回值：

无

thread_join

指令原型：

thread_join(thread_name)

指令说明：

用于同步指定线程的操作，该函数仅在主线程中生效。

参数介绍：

thread_name	线程辨识唯一字符串，不支持Unicode。 线程名称重复会提示创建失败。

返回值：

无

thread_destroy

指令原型：

thread_destroy(thread_name)

指令说明：

用于销毁指定线程的操作，该函数仅在主线程中生效。

参数介绍：

thread_name	线程辨识唯一字符串，不支持Unicode。 线程名称重复会提示创建失败。

返回值：

无

thread_enter_critical

指令原型：

thread_enter_critical()

指令说明：

用于线程进入临界区操作。

返回值：

无

thread_exit_critical

指令原型：

thread_exit_critical()

指令说明：

用于线程退出临界区操作。

返回值：

无