diff --git a/docs/API_reference/zh/QuecPython_classlib/request.md b/docs/API_reference/zh/QuecPython_classlib/request.md index cda134d9f032d4b0bf308af74299b995910450b9..254da44ac467d554ea6cdfc1ef0dc5ff69c9c27e 100644 --- a/docs/API_reference/zh/QuecPython_classlib/request.md +++ b/docs/API_reference/zh/QuecPython_classlib/request.md @@ -72,7 +72,7 @@ for i in resp.text: ### `request.put` ```python -response = requtes.put(url) +response = request.put(url) ``` 发送PUT请求。 @@ -92,7 +92,7 @@ response = requtes.put(url) ### `request.head` ```python -response = requtes.head(url) +response = request.head(url) ``` 发送HEAD请求。 diff --git a/docs/API_reference/zh/QuecPython_classlib/umqtt.md b/docs/API_reference/zh/QuecPython_classlib/umqtt.md index 06d13cedf38c006e0520ad2a341226d780a59329..5358e766c9e8c588510a704b1de2813b5668d183 100644 --- a/docs/API_reference/zh/QuecPython_classlib/umqtt.md +++ b/docs/API_reference/zh/QuecPython_classlib/umqtt.md @@ -22,21 +22,27 @@ class umqtt.MQTTClient(client_id, server, port=0, user=None, password=None, keep **参数描述：** -* `client_id` - 客户端 ID，字符串类型，具有唯一性 -* `server` - 服务端地址，字符串类型，可以是 IP 或者域名 。 -* `port` - 服务器端口（可选），int类型，默认为1883，请注意，MQTT over SSL/TLS的默认端口是8883 -* `user` - （可选) 在服务器上注册的用户名 ，字符串类型 -* `password` - （可选) 在服务器上注册的密码，字符串类型 -* `keepalive` - （可选）客户端的keepalive超时值，int类型，默认为0。 -* `ssl` - （可选）是否使能 SSL/TLS 支持 ，布尔值类型 -* `ssl_params` - （可选）SSL/TLS 参数，字符串类型 -* `reconn` - （可选）控制是否使用内部重连的标志，布尔值类型，默认开启为True -* `version` - （可选）选择使用mqtt版本，int类型，version=3开启MQTTv3.1，默认version=4开启MQTTv3.1.1 +* `client_id` - 客户端 ID，字符串类型，具有唯一性。 +* `server` - 服务端地址，字符串类型，可以是 IP 或者域名。 + +* `port` - 服务器端口（可选），整数类型，默认为1883，请注意，MQTT over SSL/TLS的默认端口是8883。 + +* `user` - （可选) 在服务器上注册的用户名，字符串类型。 + +* `password` - （可选) 在服务器上注册的密码，字符串类型。 + +* `keepalive` - （可选）客户端的keepalive超时值，整数类型，默认为0。 + +* `ssl` - （可选）是否使能 SSL/TLS 支持，布尔值类型。 + +* `ssl_params` - （可选）SSL/TLS 参数，字符串类型。 + +* `reconn` - （可选）控制是否使用内部重连的标志，布尔值类型，默认开启为True。 + +* `version` - （可选）选择使用mqtt版本，整数类型，version=3开启MQTTv3.1，默认version=4开启MQTTv3.1.1。 -**返回值描述：** -mqtt对象。 ## 设置相关功能和回调 @@ -46,16 +52,29 @@ mqtt对象。 MQTTClient.set_callback(callback) ``` - 设置回调函数，收到消息时会被调用。 +>回调函数不建议处理阻塞API，会影响mqtt消息接收。 + + **参数描述：** -* `callback` - 设置异常回调函数，function类型 +* `callback` - 设置异常回调函数，function(topic, data)类型 -**返回值描述：** +**示例：** -无 +```python +from umqtt import MQTTClient + +def data_cb(topic, data): + try: + print("umqtt recv topic[%s] data:%s:"%(topic, data)) + except Exception as e: + print("Handle error:%s"%str(e)) + +c = MQTTClient("umqtt_client", "mq.tongxinmao.com", 18830) +c.set_callback(data_cb) +``` ### `MQTTClient.error_register_cb` @@ -63,25 +82,25 @@ MQTTClient.set_callback(callback) MQTTClient.error_register_cb(callback) ``` -设置异常回调函数，umqtt内部线程异常时通过回调返回error信息，该方法在设置不使用内部重连的情况下才可触发回调 +设置异常回调函数，使用内部重连的情况下umqtt内部线程异常时通过回调返回error信息。 **参数描述：** -* `callback` - 设置异常回调函数，function类型 - -**返回值描述：** - -无 +* `callback` - 设置异常回调函数，function(error)类型 **示例：** - ```python from umqtt import MQTTClient def err_cb(err): - print("thread err:") - print(err) - + print("thread err:%s"%err) + if err == "reconnect_start": + print("start reconnect") + elif err == "reconnect_success": + print("success reconnect") + else: + print("reconnect FAIL") + c = MQTTClient("umqtt_client", "mq.tongxinmao.com", 18830) c.error_register_cb(err_cb) ``` @@ -92,18 +111,18 @@ c.error_register_cb(err_cb) MQTTClient.set_last_will(topic,msg,retain=False,qos=0) ``` -设置要发送给服务器的遗嘱，客户端没有调用disconnect()异常断开，则发送通知到客户端。 +设置要发送给服务器的遗嘱，客户端没有调用disconnect()异常断开，则发送通知到其他客户端。 **参数描述：** -* `topic` - mqtt 遗嘱主题，字符串类型 -* `msg` - 遗嘱的内容，字符串类型 -* `retain` - retain = True boker会一直保留消息，默认False，布尔值类型 -* `qos` - 布尔值类型，消息服务质量(0~1) +* `topic` - mqtt遗嘱主题，字符串类型。 -**返回值描述：** +* `msg` - 遗嘱的内容，字符串类型。 + +* `retain` - retain = True boker会一直保留消息，默认False，布尔值类型。 + +* `qos` - 整数类型，消息服务质量(0~1)。 -无 ## MQTT连接相关功能 @@ -113,16 +132,18 @@ MQTTClient.set_last_will(topic,msg,retain=False,qos=0) MQTTClient.connect(clean_session=True) ``` - 与服务器建立连接，连接失败会导致MQTTException异常。 +>mqtt相关操作要在确认connect成功后执行。 + **参数描述：** -* `clean_session` - 布尔值类型，可选参数，一个决定客户端类型的布尔值。 如果为True，那么代理将在其断开连接时删除有关此客户端的所有信息。 如果为False，则客户端是持久客户端，当客户端断开连接时，订阅信息和排队消息将被保留。默认为False +* `clean_session` - 布尔值类型，可选参数，一个决定客户端类型的布尔值。 如果为True，那么代理将在其断开连接时删除有关此客户端的所有信息。 如果为False，则客户端是持久客户端，当客户端断开连接时，订阅信息和排队消息将被保留。默认为True。 **返回值描述：** -成功返回0，失败则抛出异常 +成功返回0，失败则抛出异常。 + ### `MQTTClient.disconnect` @@ -130,15 +151,8 @@ MQTTClient.connect(clean_session=True) MQTTClient.disconnect() ``` -与服务器断开连接。 - -**参数描述：** - -无 - -**返回值描述：** +与服务器断开连接，释放相关资源。 -无 ### `MQTTClient.close` @@ -146,53 +160,43 @@ MQTTClient.disconnect() MQTTClient.close() ``` -释放socket资源,(注意区别disconnect方法，close只释放socket资源，disconnect包含线程等资源) - -注意：该方法仅用于在自己实现重连时使用，具体请参照mqtt重连示例代码，正常关闭mqtt连接请使用disconnect。 +释放socket资源,(注意区别disconnect方法，close只释放socket资源，disconnect包含线程等资源)。 -**参数描述：** +>该方法仅用于在自己实现重连时使用，具体请参照mqtt重连示例代码，正常关闭mqtt连接请使用disconnect。 -无 - -**返回值描述：** -无 ### `MQTTClient.ping` ```python MQTTClient.ping() ``` -当keepalive不为0且在时限内没有通讯活动，会主动向服务器发送ping包,检测保持连通性，keepalive为0则不开启。 - -**参数描述：** - -无 - -**返回值描述：** +当keepalive不为0且在时限内没有通讯活动，会主动向服务器发送ping包, 检测保持连通性，keepalive为0则不开启。 -无 ## 发布订阅相关功能 ### `MQTTClient.publish` ```python -MQTTClient.publish(topic,msg, retain=False, qos=0) +MQTTClient.publish(topic, msg, retain=False, qos=0) ``` -发布消息。 +发布消息到对应topic。 **参数描述：** * `topic` - mqtt 消息主题，字符串类型 + * `msg` - 需要发送的数据，字符串类型 + * `retain` - 布尔值类型，默认为False, 发布消息时把retain设置为true，即为保留信息。
MQTT服务器会将最近收到的一条RETAIN标志位为True的消息保存在服务器端, 每当MQTT客户端连接到MQTT服务器并订阅了某个topic，如果该topic下有Retained消息，那么MQTT服务器会立即向客户端推送该条Retained消息
特别注意：MQTT服务器只会为每一个Topic保存最近收到的一条RETAIN标志位为True的消息！也就是说，如果MQTT服务器上已经为某个Topic保存了一条Retained消息，当客户端再次发布一条新的Retained消息，那么服务器上原来的那条消息会被覆盖！ | -* `qos` - 布尔值类型， MQTT消息服务质量（默认0，可选择0或1）0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker + +* `qos` - 整数类型， MQTT消息服务质量（默认0，可选择0或1）0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker **返回值描述：** -无 +成功返回布尔型True，失败返回布尔型False。 ### `MQTTClient.subscribe` @@ -205,28 +209,9 @@ MQTTClient.subscribe(topic,qos) **参数描述：** -* `topic` - mqtt topic主题，字符串类型 -* `qos` - MQTT消息服务质量（默认0，可选择0或1），整型类型
0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker - -**返回值描述：** +* `topic` - mqtt topic主题，字符串类型。 -无 - -### `MQTTClient.check_msg` - -```python -MQTTClient.check_msg() -``` - -检查服务器是否有待处理消息。 - -**参数描述：** - -无 - -**返回值描述：** - -无 +* `qos` - MQTT消息服务质量（默认0，可选择0或1），整数类型
0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker。 ### `MQTTClient.wait_msg` @@ -237,14 +222,6 @@ MQTTClient.wait_msg() 阻塞等待服务器消息响应。 -**参数描述：** - -无 - -**返回值描述：** - -无 - ### `MQTTClient.get_mqttsta` @@ -252,29 +229,22 @@ MQTTClient.wait_msg() MQTTClient.get_mqttsta() ``` -获取mqtt连接状态 +获取mqtt连接状态。 注意：BG95平台不支持该API。 -PS：如果用户调用了 disconnect() 方法之后，再调用 MQTTClient.get_mqttsta() 会返回-1，因为此时创建的对象资源等都已经被释放。 +>如果用户调用了 disconnect() 方法之后，再调用 MQTTClient.get_mqttsta() 会返回-1，因为此时创建的对象资源等都已经被释放。 -**参数描述：** - -无 **返回值描述：** -无 - - -0 ：连接成功 - -1：连接中 +0：连接成功。 -2：服务端连接关闭 +1：连接中。 --1：连接异常 +2：服务端连接关闭。 +-1：连接异常。 **示例：** diff --git a/docs/API_reference/zh/QuecPython_componentlib/aLiYun.md b/docs/API_reference/zh/QuecPython_componentlib/aLiYun.md index 561210eb33cb7aa33190dcb93822ff60a59373bb..8de46d7b189156bac92dca0515fa078d3245e5ba 100644 --- a/docs/API_reference/zh/QuecPython_componentlib/aLiYun.md +++ b/docs/API_reference/zh/QuecPython_componentlib/aLiYun.md @@ -12,15 +12,25 @@ aliyun = aLiYun(productKey, productSecret, DeviceName, DeviceSecret, MqttServer) ``` -配置阿里云物联网套件的产品信息和设备信息 +配置阿里云物联网套件的产品信息和设备信息。 **参数描述：** -* `productKey` - 产品标识，字符串类型 -* `ProductSecret` - 产品密钥，字符串类型，一机一密认证方案时，此参数传入None
一型一密认证方案时，此参数传入真实的产品密钥 -* `devicename` - 设备名称 ，字符串类型 -* `DeviceSecret` - 可选参数,默认为None，设备密钥（一型一密认证方案时此参数传入None），字符串类型 -* `MqttServer` - 可选参数,需要连接的服务器名称,默认为"{productKey}.iot-as-mqtt.cn-shanghai.aliyuncs.com"，字符串类型 +* `productKey` - 产品标识，字符串类型。 + +* `ProductSecret` - 产品密钥，字符串类型，一机一密认证方案时，此参数传入None
一型一密认证方案时，此参数传入真实的产品密钥。 + +* `devicename` - 设备名称，字符串类型。 + +* `DeviceSecret` - 可选参数,默认为None，设备密钥（一型一密认证方案时此参数传入None），字符串类型。 + +* `MqttServer` - 可选参数，需要连接的服务器名称，默认为"{productKey}.iot-as-mqtt.cn-shanghai.aliyuncs.com"，字符串类型。 + +* `MqttPort` - 可选参数，需要连接的服务器端口，默认为1883，整数类型。 + +* `ssl` - 可选参数，是否使能 SSL/TLS 支持，布尔值类型。 + +* `ssl_params` - 可选参数，SSL/TLS 参数，字符串类型。 **返回值描述：** @@ -50,10 +60,13 @@ aLiYun.setMqtt(clientID, clean_session, keepAlive=300,reconn=True) **参数描述：** -* `clientID` - 自定义阿里云连接id，字符串类型 -* `clean_session` - 产品标识（唯一ID），布尔值类型，如果为True，
那么代理将在其断开连接时删除有关此客户端的所有信息。 如果为False，则客户端是持久客户端，当客户端断开连接时，订阅信息和排队消息将被保留。默认为False -* `keepAlive` - 通信之间允许的最长时间段（以秒为单位），整型类型，默认为300，范围（60-1000），建议300以上 -* `reconn` - （可选）控制是否使用内部重连的标志，布尔值类型，默认开启为True +* `clientID` - 自定义阿里云连接id，字符串类型。 + +* `clean_session` - 产品标识（唯一ID），布尔值类型，如果为True，
那么代理将在其断开连接时删除有关此客户端的所有信息。 如果为False，则客户端是持久客户端，当客户端断开连接时，订阅信息和排队消息将被保留，默认为False。 + +* `keepAlive` - 通信之间允许的最长时间段（以秒为单位），整型类型，默认为300，范围（60-1000）。 + +* `reconn` - （可选）控制是否使用内部重连的标志，布尔值类型，默认开启为True。 **返回值描述：** @@ -70,19 +83,27 @@ aLiYun.setCallback(callback) **参数描述：** -* `callback` - 设置消息回调函数，function类型，当服务端响应时触发该方法 +* `callback` - 设置消息回调函数，function(topic, data)类型，当服务端响应时触发该方法。 **回调函数参数** -* `topic` - mqtt topic主题，字符串类型 -* `msg` - 需要发送的数据，字符串类型 +* `topic` - mqtt topic主题，字符串类型。 +* `msg` - 需要发送的数据，字符串类型。 -**返回值描述：** - -无 +**示例：** +```python +from aLiYun import aLiYun +def data_cb(topic, data): + try: + print("aliyun recv topic[%s] data:%s:"%(topic, data)) + except Exception as e: + print("Handle error:%s"%str(e)) +ali = aLiYun(productKey, productSecret, DeviceName, DeviceSecret) +ali.setCallback(data_cb) +``` ### `aLiYun.error_register_cb` @@ -90,35 +111,34 @@ aLiYun.setCallback(callback) aLiYun.error_register_cb(callback) ``` -设置异常回调函数，aliyun以及umqtt内部线程异常时通过回调返回error信息，该方法在设置不使用内部重连的情况下才可触发回调 +设置异常回调函数，aliyun以及umqtt内部线程异常时通过回调返回error信息，该方法在设置使用内部重连的情况下才可触发回调。 **参数描述：** -* `callback` - 设置消息回调函数，function类型，当服务端响应时触发该方法 +* `callback` - 设置消息回调函数，function(error)类型，当服务端响应时触发该方法。 **回调函数参数** -* `msg` - 异常信息，字符串类型 - -**返回值描述：** - -无 +* `msg` - 异常信息，字符串类型。 **示例：** - ```python from aLiYun import aLiYun def err_cb(err): - print("thread err:") - print(err) + print("thread err:%s"%err) + if err == "reconnect_start": + print("start reconnect") + elif err == "reconnect_success": + print("success reconnect") + else: + print("reconnect FAIL") ali = aLiYun(productKey, productSecret, DeviceName, DeviceSecret) ali.error_register_cb(err_cb) ``` - ## 订阅发布功能 ### `aLiYun.subscribe` @@ -131,15 +151,15 @@ aLiYun.subscribe(topic,qos) **参数描述：** -* `topic` - mqtt topic主题，字符串类型 -* `qos` - MQTT消息服务质量（默认0，可选择0或1），整型类型
0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker +* `topic` - mqtt topic主题，字符串类型。 + +* `qos` - MQTT消息服务质量（默认0，可选择0或1），整型类型
0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker。 **返回值描述：** 成功返回整型值0，失败返回整型值-1。 - ### `aLiYun.publish` ```python @@ -150,9 +170,11 @@ aLiYun.publish(topic,msg, qos=0) **参数描述：** -* `topic` - mqtt topic主题，字符串类型 -* `msg` - 需要发送的数据，字符串类型 -* `qos` - MQTT消息服务质量（默认0，可选择0或1），整型类型
0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker +* `topic` - mqtt topic主题，字符串类型。 + +* `msg` - 需要发送的数据，字符串类型。 + +* `qos` - MQTT消息服务质量（默认0，可选择0或1），整型类型
0：发送者只发送一次消息，不进行重试 1：发送者最少发送一次消息，确保消息到达Broker。 **返回值描述：** @@ -168,15 +190,6 @@ aLiYun.start() 运行连接。 -**参数描述：** - -无 - -**返回值描述：** - -无 - - ### `aLiYun.disconnect` @@ -186,13 +199,6 @@ aLiYun.disconnect() 关闭连接。 -**参数描述：** - -无 - -**返回值描述：** - -无 ### `aLiYun.ping` @@ -200,17 +206,9 @@ aLiYun.disconnect() aLiYun.ping() ``` -发送心跳包 - -**参数描述：** - -无 - -**返回值描述：** - -无 - +发送心跳包。 +>无需单独处理，设置keepalive后，会自动发送。 ### `aLiYun.getAliyunSta` @@ -218,28 +216,22 @@ aLiYun.ping() aLiYun.getAliyunSta() ``` -获取阿里云连接状态 - -注意：BG95平台不支持该API。 - -**参数描述：** +获取阿里云连接状态。 -无 +>BG95平台不支持该API。 **返回值描述：** -* 0 ：连接成功 - -* 1：连接中 +* 0 ：连接成功。 -* 2：服务端连接关闭 +* 1：连接中。 -* -1：连接异常 +* 2：服务端连接关闭。 +* -1：连接异常. **示例：** - ```python import log