SmartBus client Python wrapper¶

smartbus.errors module¶

错误信息定义

exception smartbus.errors.AlreadyExistsError¶

基类：Exception

对象已经存在，无法再次新建

exception smartbus.errors.AlreadyInitializedError¶

基类：Exception

已经初始化，无法重复的初始化

exception smartbus.errors.InvokeFlowIdError¶

基类：Exception

收到调用流程的返回结果时，ID无法匹配

exception smartbus.errors.NotInitializedError¶

基类：Exception

尚未初始化，无法使用

exception smartbus.errors.SmartBusError(code, message)¶

基类：Exception

SmartBus 通信错误

code¶

SmartBus错误码

message¶

错误信息

smartbus.errors.check(code, raise_if_err=True)¶

检查 SmartBus 客户端 C-API 的返回结果是否正确

参数:	code (int) – 要检查的返回结果编码 raise_if_err (bool) – 是否在发现错误时抛出异常。默认为真。
返回:	当 raise_if_err 为 True 时，无错误则返回 None，有错误则抛出错误异常； 当 raise_if_err 为 False 时，无错误则返回 None，有错误则返回错误异常实例。

smartbus.head module¶

class smartbus.head.Head(ptr)¶

基类：object

Smartbus通信包头信息

每当接收到数据时，所触发的事件中，都包含该类型的参数，记录了一些数据包的相关信息

对应 SMARTBUS_PACKET_HEAD 结构体的 ctypes 数据类型 PacketHeader 的再次封装

参数:	ptr (smartbus._c.mutual.PPacketHeader) – 结构体指针

cmd¶

命令

一条 SmartBus 数据的命令关键字

cmd_type¶

命令类型

一条 SmartBus 数据的命令类型

data_length¶

正文数据长度

dst_unit_client_id¶

接收者客户端ID

dst_unit_client_type¶

接收者客户端类型

dst_unit_id¶

接收者节点ID

packet_size¶

包长度

src_unit_client_id¶

发送者客户端ID

src_unit_client_type¶

发送者客户端类型

src_unit_id¶

发送者节点ID

smartbus.ipc module¶

面向对象样式的 IPC 客户端 API 的 Python 封装

class smartbus.ipc.Client(client_id, client_type, user=None, password=None, info=None, lib_path='', event_executor=None)¶

基类：smartbus.utils.LoggerMixin

IPC 客户端

注解

使用 create() 或者 get_or_create() 建立实例，不要直接使用构造函数！

参数:	client_id (int) – client_type (int) – user (str) – 用户名 password (str) – 密码 info (str) – 附加信息 lib_path (str) – SO/DLL 文件路径名。 默认值是 None : 将按照 DLL_NAME 查找库文件，需确保库文件在 Python 运行时的搜索路径中。 event_executor (ThreadPoolExecutor) – 事件执行器。在此执行器中回调事件执行函数。 默认执行器的线程池数量是 1
引发:	SmartBusError – 如果建立连接的尝试失败

加载 Smartbus IPC 客户端 so/dll 到这个 Python 包, 并进行初始化。

activate()¶

激活客户端

将建立连接。连接一旦建立，就可以接受/发送数据，

注意

该函数立即返回，无论连接成功与否。 如该函数没有直接返回失败，客户端会自动尝试连接 smartbus 服务器，并在连接断开/失败时自动尝试重连

client_id¶

client_type¶

classmethod create(*args, **kwargs)¶

创建 Singleton 实例

返回:	新建的实例
返回类型:	Client

classmethod destroy()¶

dispose()¶

必须 调用该方法方可释放

classmethod get()¶

获取 Singleton 实例

返回:	存在的实例
返回类型:	Client

classmethod get_or_create(*args, **kwargs)¶

创建或者返回 Singleton 实例

返回:	存在的或者新建的实例
返回类型:	Client

• 如果实例存在，相当于 get()
• 如果实例不存在，相当于 create()

info¶

classmethod instance()¶

获取 Singleton 实例

返回:	存在的实例
返回类型:	Client

launch_flow(server_unit_id, process_index, project_id, flow_id, mode, timeout, params)¶

调用流程

参数:	server_unit_id (int) – 目标 IPSC 服务器 smartbus 单元ID process_index (int) – IPSC 进程 ID ，同时也是该 IPSC 进程的 smartbus Client ID project_id (str) – 流程项目ID flow_id (str) – 流程ID mode (int) – 调用模式：0 有流程返回、1 无流程返回 timeout (float) – 有流程返回时的等待超时值（秒） params (list) – 流程输入参数里表。简单数据类型JSON数组。 子流程开始节点的传人参数自动变换为list类型数据。 对应的字符串内容最大长度不超过32K字节。
返回:	invoke_id，调用ID，用于流程结果返回匹配用途。
返回类型:	int

notify(server_unit_id, process_index, project_id, title, mode, expires, txt)¶

发送通知消息

参数:	server_unit_id (int) – 目标IPSC服务器 smartbus 单元ID process_index (int) – IPSC 进程ID，同时也是该IPSC进程的 smartbus client-id project_id (str) – 流程项目ID title (str) – 通知的标题 mode (int) – 调用模式。目前无意义，一律使用0 expires (float) – 消息有效期。单位秒 txt (str) – 消息文本（对于 Python2 bytes string, 必须 使用 utf-8 编码）
返回:	调用任务的ID。
返回类型:	int
Except:	API返回错误

on_connect()¶

连接成功

on_connect_fail(error_code)¶

连接失败

on_data(head, data)¶

接收到了数据

参数:	head (Head) – 消息头 data (bytes) – bytes 二进制数据

on_disconnect()¶

连接断开

on_flow_ack(head, project_id, invoke_id, status_code, msg)¶

流程启动确认

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID status_code (int) – 状态码. 1表示正确. msg (str) – 错误信息

on_flow_error(head, project_id, invoke_id, error_code)¶

流程执行错误

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID error_code (int) – 错误码

on_flow_resp(head, project_id, invoke_id, params)¶

调用流程结果返回

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID params (list) – 流程返回值结果串, 采用 JSON Array 格式，对应于被调用流程的“子项目结束”节点的返回值列表

on_flow_timeout(head, project_id, invoke_id)¶

流程执行超时

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID

on_global_connect_state_changed(unit_id, client_id, client_type, access_unit_id, status_code, info)¶

全局节点客户端连接、断开事件

参数:	unit_id (int) – 发生连接或断开事件的Smartbus节点单元ID client_id (int) – 发生连接或断开事件的Smartbus节点单元中的客户端ID client_type (int) – 发生连接或断开事件的Smartbus节点单元中的客户端类型 access_unit_id (int) – 连接点的UnitID status_code (int) – 连接状态码： 0 断开连接、1 新建连接、2 已有的连接 info (str) – 连接附加信息

当smartbus上某个节点发生连接或者断开时触发。

password¶

ping(dst_unit_id, dst_client_id, dst_client_type, data=None)¶

发送PING命令

参数:	dst_unit_id (int) – 目标的smartbus单元ID dst_client_id (int) – 目标的smartbus客户端ID dst_client_type (int) – 目标的smartbus客户端类型 data (bytes) – 待发送数据，类型必须是 bytes

send_data(cmd, cmd_type, dst_unit_id, dst_client_id, dst_client_type, data)¶

发送数据

参数:	cmd (int) – 命令 cmd_type (int) – 命令类型 dst_unit_id (int) – 目标节点ID dst_client_id (int) – 目标客户端ID dst_client_type (int) – 目标客户端类型 data (bytes) – 待发送数据，类型必须是 bytes

user¶

smartbus.net module¶

面向对象样式的 NET 客户端 API 的 Python 封装

class smartbus.net.Client(client_id, client_type, master_ip, master_port, slave_ip=None, slave_port=None, user=None, password=None, info=None, event_executor=None)¶

基类：smartbus.utils.LoggerMixin

NET 客户端

注解

使用 create() 建立实例，不要直接使用构造函数！

警告

实例一旦建立，无法释放！

参数:	client_id (int) – 本地 client id, >= 0 and <= 255 client_type (int) – 本地 client type master_ip (str) – 主服务器IP地址 master_port (int) – 主服务器端口 slave_ip (str) – 从服务器IP地址。没有从地址的，填写0，或者”“ slave_port (int) – 从服务器端口。没有从端口的，填写0xFFFF user (str) – 用户名 password (int) – 密码 info (str) – 附加信息 event_executor (ThreadPoolExecutor) – 事件执行器。在此执行器中回调事件执行函数。默认执行器的线程池数量是 1

activate()¶

激活客户端

将建立连接。连接一旦建立，就可以接受/发送数据，

注意

该函数立即返回，无论连接成功与否。 如该函数没有直接返回失败，客户端会自动尝试连接 smartbus 服务器，并在连接断开/失败时自动尝试重连

client_id¶

client_type¶

classmethod create(*args, **kwargs)¶

建立实例

参数见构造函数

classmethod find(client_id, default=None)¶

查找并返回实例

参数:	client_id – 要查找的实例的 client_id default – 如果找不到，返回这个值
返回:	找到的实例
返回类型:	Client

info¶

classmethod initialize(unit_id, global_connect_callback=None, lib_path='')¶

初始化

参数:	unit_id (int) – 在连接到 Smartbus 后，本节点的单元ID。 global_connect_callback (callable) – 全局连接事件回调函数 lib_path (str) – SO/DLL 文件路径名。 默认值是 None : 将按照 DLL_NAME 查找库文件，需确保库文件在 Python 运行时的搜索路径中。

警告

unit_id >= 16 ，且全局唯一，不得重复

全局节点客户端连接、断开事件，当smartbus上某个节点发生连接或者断开时触发。 其函数形如：

global_connect_callback(unit_id, client_id, client_type, access_unit_id, status_code, info)¶

参数:	unit_id (int) – 发生连接或断开事件的Smartbus节点单元ID client_id (int) – 发生连接或断开事件的Smartbus节点单元中的客户端ID client_type (int) – 发生连接或断开事件的Smartbus节点单元中的客户端类型 access_unit_id (int) – 连接点的UnitID status_code (int) – 连接状态码： 0 断开连接、1 新建连接、2 已有的连接 info (str) – 连接附加信息

launch_flow(server_unit_id, process_index, project_id, flow_id, mode, timeout, params)¶

调用流程

参数:	server_unit_id (int) – 目标 IPSC 服务器 smartbus 单元ID process_index (int) – IPSC 进程 ID ，同时也是该 IPSC 进程的 smartbus Client ID project_id (str) – 流程项目ID flow_id (str) – 流程ID mode (int) – 调用模式：0 有流程返回、1 无流程返回 timeout (float) – 有流程返回时的等待超时值（秒） params (list) – 流程输入参数里表。简单数据类型JSON数组。 子流程开始节点的传人参数自动变换为list类型数据。 对应的字符串内容最大长度不超过32K字节。
返回:	invoke_id，调用ID，用于流程结果返回匹配用途。
返回类型:	int

master_ip¶

master_port¶

notify(server_unit_id, process_index, project_id, title, mode, expires, txt)¶

发送通知消息

参数:	server_unit_id (int) – 目标IPSC服务器 smartbus 单元ID process_index (int) – IPSC 进程ID，同时也是该IPSC进程的 smartbus client-id project_id (str) – 流程项目ID title (str) – 通知的标题 mode (int) – 调用模式。目前无意义，一律使用0 expires (float) – 消息有效期。单位秒 txt (str) – 消息文本（对于 Python2 bytes string, 必须 使用 utf-8 编码）
返回:	调用任务的ID。
返回类型:	int
Except:	API返回错误

on_connect()¶

连接成功

on_connect_fail(error_code)¶

连接失败

on_data(head, data)¶

接收到了数据

参数:	head (Head) – 消息头 data (bytes) – bytes 二进制数据

on_disconnect()¶

连接断开

on_flow_ack(head, project_id, invoke_id, status_code, msg)¶

流程启动确认

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID status_code (int) – 状态码. 1表示正确. msg (str) – 错误信息

on_flow_error(head, project_id, invoke_id, error_code)¶

流程执行错误

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID error_code (int) – 错误码

on_flow_resp(head, project_id, invoke_id, params)¶

调用流程结果返回

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID params (list) – 流程返回值结果串, 采用 JSON Array 格式，对应于被调用流程的“子项目结束”节点的返回值列表

on_flow_timeout(head, project_id, invoke_id)¶

流程执行超时

参数:	head (Head) – 消息头 project_id (str) – 流程项目ID invoke_id (int) – 流程调用ID

password¶

ping(dst_unit_id, dst_client_id, dst_client_type, data=None)¶

发送PING命令

参数:	dst_unit_id (int) – 目标的smartbus单元ID dst_client_id (int) – 目标的smartbus客户端ID dst_client_type (int) – 目标的smartbus客户端类型 data (bytes) – 待发送数据，类型必须是 bytes

send_data(cmd, cmd_type, dst_unit_id, dst_client_id, dst_client_type, data)¶

发送数据

参数:	cmd (int) – 命令 cmd_type (int) – 命令类型 dst_unit_id (int) – 目标节点ID dst_client_id (int) – 目标客户端ID dst_client_type (int) – 目标客户端类型 data (bytes) – 待发送数据，类型必须是 bytes

slave_ip¶

slave_port¶

unit_id¶

user¶

smartbus.utils module¶

Some helper functions

smartbus.utils.b2s_recode(bs, source_encoding=None, target_encoding=None)¶

将 bytes 字符串重编码为 str 字符串

参数:	bs (bytes) – 待转换字节字符串 source_encoding (str) – bytes 的编码格式。 默认 utf-8。 target_encoding (str) – 转换结果字符串的编码格式。 仅 Python2 环境下有效。
返回:	转换结果字符串
返回类型:	str

smartbus.utils.s2b_recode(s, source_encoding=None, target_encoding=None)¶

将 str 字符串重编码为 bytes 字符串

参数:	s (str) – 待转换字节字符串 source_encoding (str) – bytes 的编码格式。 仅 Python2 环境下有效。 target_encoding (str) – 转换结果字符串的编码格式。
返回:	转换结果字符串
返回类型:	bytes

smartbus.utils.to_bytes(s, encoding='utf-8')¶

Convert to bytes string.

参数:	s – String to convert. encoding (str) – Encoding codec.
返回:	bytes string, it’s bytes or str in Python 2.x, bytes in Python 3.x.
返回类型:	bytes

• In Python 2, convert s to bytes if it’s unicode.
• In Python 2, return original s if it’s not unicode.
• In Python 2, it equals to to_str().
• In Python 3, convert s to bytes if it’s unicode or str.
• In Python 3, return original s if it’s neither unicode nor str.

smartbus.utils.to_str(s, encoding='utf-8')¶

Convert to str string.

参数:	s – String to convert. encoding (str) – Decoding codec.
返回:	str string, it’s bytes in Python 2.x, unicode or str in Python 3.x.
返回类型:	str

• In Python 2, convert s to str if it’s unicode.
• In Python 2, return original s if it’s not unicode.
• In Python 2, it equals to to_bytes().
• In Python 3, convert s to str if it’s bytes.
• In Python 3, return original s if it’s not bytes.
• In Python 3, it equals to to_unicode().

smartbus.utils.to_unicode(s, encoding='utf-8')¶

Convert to unicode string.

参数:	s – String to convert. encoding (str) – Encoding codec.
返回:	unicode string, it’s unicode in Python 2.x, str or unicode in Python 3.x.
返回类型:	unicode

• In Python 2, convert s to unicode if it’s str or bytes.
• In Python 2, return original s if it’s neither str or bytes.
• In Python 3, convert s to str or unicode if it’s bytes.
• In Python 3, return original s if it’s not bytes.
• In Python 3, it equals to to_str().

class smartbus.utils.LoggerMixin¶

基类：object

Mixin Class provide a logger property

classmethod get_logger()¶

logger instance.

返回类型:	logging.Logger

logger name format is ModuleName.ClassName

logger¶

logger instance.

返回类型:	logging.Logger

logger name format is ModuleName.ClassName