.. _存储格式与add_data_item:

=============================
存储格式与add_data_item
=============================

-----------------------------
存储格式格式
-----------------------------
 每当函数 ``on_start`` 执行结束，如果在执行过程中使用函数 ``add_data_item`` 进行添加保存数据项，则按照如下格式存储数据。


         +---------------+-------------+------------+-----------------+--------------------+
         |通道总个数     |通道ID和数据 |通道ID和数据| ...             |通道ID和数据        |
         +===============+=============+============+=================+====================+
         | 1 Byte        |不定长字节   |不定长字节  | ...             |不定长字节          |
         +---------------+-------------+------------+-----------------+--------------------+

         - 通道总个数：数据内容中包含的通道个数
         - 同一包数据中，可能有相同的通道ID，依据出现的顺序进行区别
         - 数据内容中包含个各要素的采集数据

 通道定义格式

         +------------------------------------------+------------+--------------------------------------+
         |通道ID                                    |通道数据类型| 数据内容                             |
         +=====================+====================+============+======================================+
         |主类型ID / MID 1Byte |子类型ID / CID 1Byte|   1 Byte   | n Byte                               | 
         +---------------------+--------------------+------------+--------------------------------------+

        - 通道ID：用于区别不同通道，包括主类型和子类型，具体请参见通道编号说明
        - 通道数据类型：用以定义通道数据内容的格式，如下

         +-----------------------------+--------------------------+--------------------------------------+
         |01h                          |Unsigned char             | 1 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |02h                          |Signed char               | 1 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |03h                          |Unsigned int              | 2 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |04h                          |Signed int                | 2 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |05h                          |Unsigned long             | 4 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |06h                          |Signed long               | 4 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |07h                          |Float                     | 4 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |08h                          |BCD HH                    | 1 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |09h                          |BCD MMHH                  | 2 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |10h                          |BCD YYMMDDHHmmss          | 6 Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+
         |11h                          |String                    | n Byte                               |
         +-----------------------------+--------------------------+--------------------------------------+

 每当脚本中调用函数 ``add_data_item`` ，《数据内容格式》中通道总个数加1，并按顺序增加一组新的通道ID和数据

 
 以下为一帧数据：

 +---+---+---+----+----+---+---+----+----+---+---+----+-----------------+---+---+----+-----+---+---+----+-----+
 |Num|MID|CID|TYPE|DATA|MID|CID|TYPE|DATA|MID|CID|TYPE|DATA             |MID|CID|TYPE|DATA |MID|CID|TYPE|DATA |
 +===+===+===+====+====+===+===+====+====+===+===+====+==+==+==+==+==+==+===+===+====+==+==+===+===+====+==+==+
 |05 |00 |01 | 01 |0C  |00 |02 |01  |17  |00 |03 |10  |18|08|22|20|52|00|06 |03 |04  |00|00|06 |02 |04  |00|01|
 +---+---+---+----+----+---+---+----+----+---+---+----+--+--+--+--+--+--+---+---+----+--+--+---+---+----+--+--+


-----------------------
add_data_item
-----------------------
 调用该函数时，向内存缓存中添加一个数据项，每个数据项由 ``MID`` ， ``CID`` ， ``TYPE`` ， ``DATA`` 构成，详细定义参考上述数据格式。
 每调用一次，数据格式的 ``NUM`` 增一。当本次 ``on_start`` 执行结束（回调函数结束）时，数据从内存缓存 保存至 非易失存储器。

.. note::
        数据上传时也按照 **存储格式** 进行上传。
        ``MID`` , ``CID`` 用于标记唯一传感器通道。 ``TYPE`` 用于标记数据类型，进而帮助解析 ``DATA`` 数据。

.. warning::
         ``MID`` ， ``CID`` ， ``TYPE`` ， ``DATA`` 由脚本编写者指定，更需要跟服务器端一一对应，否则无法正确解析跟显示数据。

-----------------------
天星智联通道定义
-----------------------

 :download:`通道定义 <../_static/通道编号说明-标准.xls>`