:mod:`linkkit` --- 对接阿里云物联网平台
====================================================

.. mod:: linkkit
.. linkkit.LinkKit:

阿里云物联网平台提供安全可靠的设备连接通信能力，支持设备数据采集上云，规则引擎流转数据和云端数据下发设备端。此外，也提供方便快捷的设备管理能力，支持物模型定义，数据结构化存储，和远程调试、监控、运维。
基于linkkit模块可以简单快速的使用阿里云物联网平台能力。


linkkit模块的主要实现是是一个LinkKit 类，通过它的构造函数获取linkkit实例，就可以轻松设置相关回调函数和调用相关方法。linkkit 中涉及三个基本概念如下:

- 属性(prop)
   云端/设备端数据互通的通道，云端通过改变prop值，反馈到设备端，设备端修改prop值，保存到云端

- 事件(event)
   设备端到云端的事件通知

- 服务(service)
   云端到设备端的服务调用

详细使用示例请参考主页"参考案例"中的云端连接/控制部分

类
-------
.. class:: LinkKit(...)


构造函数
***********


.. class:: LinkKit(host_name, product_key, device_name, device_secret,product_secret=None, user_data=None)

   
   LinkKit 初始化实例的方法

   - ``host_name`` 默认值为"cn-shanghai"

   - ``product_key`` 物联网平台的pk

   - ``device_name`` 默认值为"cn-shanghai"

   - ``device_secret`` 物联网平台的pk
   
   - ``product_secret`` 物联网平台的pk

      - ``动态注册``  这个参数不需要传，会在设备注册的时候，通过云端返回给设备端，设备端保存下来，并进行连接操作

      - ``静态注册``  物联网平台的上的ps

   - ``user_data`` 用户数据，视情况而定，可以不传 

   使用示例::

      from linkkit import linkkit
      
      lk = linkkit.LinkKit(host_name="cn-shanghai",
         product_key=PRODUCT_KEY,
         device_name=DEVICE_NAME,
         device_secret=DEVICE_SECRET,
         product_secret=PRODUCT_SECRET)  


方法
***********
.. method:: connect_async()

   连接物联网平台连接函数，该函数是异步调用，会通过on_connect 和on_disconnect 返回连接结果
   


.. method:: thing_post_property(payload)

   设置一个property 属性

   使用示例::

      import ujson
      def property_test():
          num = 100
          while(num > 0):
             property_test = {
                 "test_prop": num
             }
             payload = ujson.dumps(property_test)
             request_id = lk.thing_post_property(payload)
             num = num -20

.. method:: thing_trigger_event(payload)

   触发一个event 事件

   使用示例::

      import ujson
      def do_post_event_test():
          num = 100
          while(num > 0):
          event_test = {
              "test_event": num
          }
          payload = ujson.dumps(event_test)
          lk.thing_trigger_event(("EventTest",payload))
          num = num - 20
  

.. method:: do_yield(timeout)

   激活物联网平台接收云端消息，并设置接收超时时间为:timeout, 单位是 ms
   为了保证云端消息被接收到，执行了异步命令以后，需要循环执行这个方法，直到拿云端的返回



回调函数
***********

   on_connect
      连接成功的回调函数,属性类型:无参函数

      使用示例::

         def on_connect():
             print('linkkit connected')

         lk.on_connect = on_connect


   on_disconnect
      断开连接的回调函数,属性类型：无参函数

      使用示例::

         def on_disconnect():
             print('linkkit disconnected')

         lk.on_disconnect = on_disconnect


   on_thing_prop_post
      设置prop回调函数,属性类型：两个入参的函数

      使用示例::

         def on_thing_prop_post(id,code):
             print(' on report reply: id is %d , code is %d  ' %(id,code))
         
         lk.on_thing_prop_post = on_thing_prop_post


   on_thing_event_post
      触发event回调函数,属性类型：两个入参的函数

      使用示例::

         def on_thing_event_post(id,code):
             print("on_trigger_event_reply: id is %d ,code is %d " %(id,code))

         lk.on_thing_event_post = on_thing_event_post


   on_prop_set
      服务端调用设备端，设置prop,属性类型：一个入参的函数

      使用示例::

         def on_prop_set(request):
             print("on_prop_set: request is %s  " %(request))

         lk.on_prop_set  = on_prop_set

   on_service_request
      服务端调用设备端的服务,属性类型：两个入参的函数

      使用示例::

         def on_service_request(request,response):
             print("on_service_request: request is %s ,response is %s " %(request,response))

         lk.on_service_request = on_service_request