• 貝殼物聯平臺通訊協議

    貝殼物聯平臺通訊協議TCP、UDP、HTTP、Websocket說明,設備登錄服務器,收發命令,發送實時數據,上傳圖片等協議。

    目錄

    一、概述

    二、通訊地址

    三、通訊數據格式

    四、命令列表

    1、設備登錄 2、發送實時數據 3、用戶和設備上線通知 4、用戶和設備下線通知 5、用戶與設備、設備與設備、用戶與用戶間溝通指令數據 6、查詢設備或用戶是否在線 7、查詢當前設備狀態 8、發送報警信息 9、查詢服務器時間 10、強制目標設備下線

    五、PC端模擬測試

    六、用戶相關指令

    一、概述

        貝殼物聯云平臺采用以TCP協議為主,UDP協議為輔的形式進行通訊,兩種協議間信息互通(主要為UDP可以發送指令給TCP在線設備)。

        在TCP協議的基礎上,可以直接使用TCP或者websocket建立長連接,定時發送心跳數據,保持用戶、設備在線,在線期間與服務器可進行Json字符串格式數據進行通訊,也可采用http(s)通訊協議獲取用戶資源、向設備發送指令、上傳圖片等。

        以UDP協議為基礎的通訊,設備可不必保持在線,隨時在需要的時候向服務器發送指令進行相關操作。

    1. https上傳圖片協議

    2. UDP通訊協議

    3. TCP(websocket)長連接協議,如下。

    二、通訊地址

    貝殼物聯通訊框架圖

    通訊方式:TCP或websocket

    地址:www.smgyp.com

    TCP端口:8181、8282、8585(ssl加密)

    Websocket端口:8383、8484(ssl加密)

    8181端口——服務器不主動發送心跳包,靠客戶端主動發送心跳包保持在線,心跳間隔以40~50s為佳;

    8282端口——服務器主動向客戶端發送心跳包

    {"M":"b"}\n

    每40s發送一次,如果兩次沒有應答(即在80s內沒有向服務器發送有效數據),服務將自動與客戶端斷開連接。

    8383端口(ws://)——服務器主動向客戶端發送心跳包

    {"M":"ping"}

    每30s發送一次,如果兩次沒有應答(即在60s內沒有向服務器發送有效數據),服務將自動與客戶端斷開連接。

    8484端口(wss://)——心跳同8383

    8585端口(tcp+ssl)——心跳同8181

    心跳包格式:任何符合通訊數據格式的字符串均可(websocket可不帶\n),如:

    {"M":"beat"}\n

    三、通訊數據格式

    Json字符串+換行符
    形如:{"M":"beat"}\n
    稱之為Json New Line。

    四、命令列表

    1、設備登錄 (加密

    {"M":"checkin","ID":"xx1","K":"xx2"}\n

    說明:
    M —— 固定(Method)
    checkin —— 固定,登錄指令
    ID —— 固定
    xx1 —— 可變,設備ID,在會員中心查看
    K —— 固定(apiKey)
    xx2 —— 可變,設備apikey,在會員中心查看
    設備登錄后,如果在1分鐘內無數據傳送,連接將被自動關閉。
    若保持設備長期在線,可每隔50秒向服務器發送一次信息,任何信息均可。

    返回結果(登錄信息正確時返回,錯誤無任何返回,如果設備已登錄,也將無任何返回信息,且不會登錄成功):

    {"M":"checkinok","ID":"xx1","NAME":"xx2","T":"xx3"}\n

    說明:
    M —— 固定(Method)
    checkinok —— 固定,設備登錄成功指令
    ID —— 固定
    xx1 —— 可變,設備登錄成功后,用于通訊的唯一ID,其組成為字符“D"+設備ID,如D24

    NAME —— 固定
    xx2 —— 可變,該設備的名稱
    T —— 固定(time)
    xx3 —— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數。

    2、發送實時數據

    {"M":"update","ID":"xx1","V":{"id1":"value1",...}}\n

    說明:此命令無返回信息,兩次發送間隔不得小于5s,發送數據前應確保該設備已登錄在線。

    M —— 固定(Method)
    update —— 固定,實時更新數據指令(可用 u 代替 update,減小命令長度)
    ID —— 固定
    xx1 —— 可變,設備ID,在會員中心查看
    V —— 固定(Value)
        id1 —— 可變,數據接口ID,在會員中心查看
        value1 —— 可變(數值型),本地數據(譬如:傳感器測量數據)
        ... —— 可以更新該設備下多個數據接口的數據

    示例

    一次上傳單個接口數據示例:

    {"M":"update","ID":"2","V":{"2":"120"}}\n

    同時上傳多個接口數據示例:

    {"M":"update","ID":"112","V":{"6":"1","36":"116"}}\n

    實時上傳定位接口數據示例:

    {"M":"update","ID":"112","V":{"36":"116,40"}}\n

    其中116為經度值,40是為維度值,詳見:定位數據上傳說明

    3、用戶和設備上線通知數據

    {"M":"login","ID":"xx1","NAME":"xx2","T":"xx3"}\n

    說明:用戶和設備登錄成功后,貝殼服務器會向所屬用戶,及該用戶名下所有其他設備發此信息

    M —— 固定(Method)
    login —— 固定,用戶或設備登錄成功指令
    ID —— 固定
    xx1 —— 可變,用戶登錄成功后,用于通訊的唯一ID,其組成為字符“U"+用戶ID,如U23
    NAME —— 固定
    xx2 —— 可變,用戶的名稱
    T —— 固定(time)
    xx3 —— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數。

    4、用戶或設備下線通知數據

    {"M":"logout","ID":"xx1","NAME":"xx2","T":"xx3"}\n

    說明:設備和用戶離線后,貝殼服務器會向所屬用戶,及該用戶名下其他所有設備發此信息

    M —— 固定(Method)

    logout —— 固定,用戶或設備下線指令

    ID —— 固定

    xx1 —— 可變,下線設備或用戶的唯一通訊ID,其組成為字符"D"+設備ID、"U"+用戶ID、"P"+游客ID,如D24、U23

    NAME —— 固定

    xx2 —— 可變,下線設備或用戶的名稱

    T —— 固定(time)
    xx3 —— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數

    5、用戶與設備、設備與設備、用戶與用戶間溝通指令數據

    發送指令格式:

    {"M":"say","ID":"xx1","C":"xx2","SIGN":"xx3"}\n

    提醒:此命令發送目標不受限制,無論目標是否屬于自己,無論是用戶、游客還是設備,只要對方在線都將收到此指令(設置為不公開監聽的除外)。

    M —— 固定(Method)
    say —— 固定,溝通指令(可用 s 代替 say,減小命令長度)
    ID —— 固定

    xx1 —— 可變,發送目標的唯一通訊ID,其組成為字符"D"+設備ID、"U"+用戶ID、"G"+群組ID、"P"+游客ID,如D24、U23,當xx1為“ALL”時,將向該用戶及其名下所有設備發送該消息

                  xx1也可以是多個通訊ID組成的數組,用于同時向多個設備發送信息,此時的寫法為 "ID":["U2","D112","D21","G11"] ,方括號及其內容替代"xx1"

                  注:當發送目標是群組時,只有當前登錄設備或用戶屬于目標群組,才能發送成功。

    C —— 固定(content)

    xx2 —— 可變(數據類型自定,符合Json字符串要求即可),發送指令內容

    SIGN —— 固定(可選)

    xx3 —— 可變(可選),自定義字符串,可用于對指令的簽名標識

    對方接收到的指令格式:

    {"M":"say","ID":"xx1","NAME":"xx2","C":"xx3","SIGN":"xx4","T":"xx5","G":"xx6"}\n

    提醒:此指令不管設備公開還是隱藏都將收到,可能來自游客、其他用戶或其他用戶的設備,重要操作請對指令來源ID進行判斷。設備設置為不公開監聽,可拒絕接收非同一用戶名下設備發來的消息(當信息來自群組消息時,不受此限制)。

    M —— 固定(Method)

    say —— 固定,溝通指令

    ID —— 固定

    xx1 —— 可變,指令來源的唯一通訊ID,其組成為字符"D"+設備ID、"U"+用戶ID、"P"+游客ID,如D24、U23

    NAME —— 固定

    xx2 —— 可變,指令來源的名稱

    C —— 固定(content)

    xx3 —— 可變(數據類型自定,符合Json字符穿要求即可),發送指令內容

    SIGN —— 固定(可選)

    xx4 —— 可變(可選),來自指令發送方的簽名標識

    T —— 固定(time)
    xx5 —— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數

    G —— 固定(可選),當信息來自群組時,會有此項,可用此項判斷信息是否來自群組。

    xx6 —— 可變,群組ID,形如"G20"

    6、查詢設備或用戶是否在線

    {"M":"isOL","ID":["xx1",...]}\n

    說明:可以查詢設備自身和其他設備及用戶在線狀態,兩次查詢間隔不得小于10s,此命令使用前需登錄。

    M —— 固定(Method)

    isOL —— 固定,是否在線查詢指令

    ID —— 固定

        xx1 —— 可變,目標設備或用戶的唯一通訊ID,其組成為字符"D"+設備ID、"U"+用戶ID、"P"+游客ID,如D24、U23

        ... —— 可以同時查詢多個目標

    返回結果:

    {"M":"isOL","R":{"XX1":"xx1",...},"T"":"xx3"}\n

    M —— 固定(Method)

    isOL —— 固定,是否在線查詢指令

    R —— 固定(Respone)

        XX1 —— 可變,查詢目標設備或用戶的唯一通訊ID,其組成為字符"D"+設備ID、"U"+用戶ID、"P"+游客ID,如D24、U23

        xx1 —— 可變,XX1的查詢結果0或1,0代表不在線,1代表在線

        ... —— 多個查詢結果

    T —— 固定(time)
    xx2—— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數

    7、查詢當前設備狀態

    {"M":"status"}\n

    說明:(兩次查詢間隔不得小于10s)

    M —— 固定(Method)

    status —— 固定,查詢當前設備狀態指令(可用 t 代替 status,減小命令長度)

    返回結果:

    {"M":"xx1"}\n

    M —— 固定(Method)

    xx1 —— 可變(connected/checked),當前設備狀態,connected代表已連接服務器尚未登錄,checked代表已連接且登錄成功

    8、發送報警信息

    {"M":"alert","ID":"xx1","C":"xx2"}\n

    說明:(設備主動發送報警信息,通過觸發已在用戶中心設置的報警提示,可通過郵件、微博、釘釘機器人、微信(方糖)、webhook等方式,對外發送指定提示內容。兩次發送間隔不得小于10min,無返回)

    M —— 固定(Method)

    alert —— 固定,設備主動發送報警指令

    ID —— 固定

    xx1 —— 可變,要觸發的報警提示ID,可在用戶中心查看或添加。

    C —— 固定(Content)

    xx1 —— 可變,自定義的報警內容。

    9、查詢服務器時間

    {"M":"time","F":"xx1"}\n

    說明:(需在設備登錄后進行查詢,兩次查詢間隔不得小于10s)

    M —— 固定(Method)

    time —— 固定,查詢服務器時間指令

    F —— 固定(Format)

    xx1 —— 可變,定義返回格式stamp(返回:1466659300)、Y-m-d(返回:2016-06-21)、Y.m.d(返回:2016.06.21)、Y-m-d H:i:s(返回:2016-06-21 10:25:30)

    返回結果

    說明:查詢過快或格式錯誤無返回

    {"M":"time","T":"xx1"}\n

    M —— 固定(Method)

    time —— 固定,查詢服務器時間返回指令

    T —— 固定(Time)

    xx1 —— 可變,根據查詢格式返回服務器的時間

    10、強制目標設備下線

    {"M":"checkout","ID":"xx1","K":"xx2"}\n

    說明:發送此命令無需登錄,只需與服務建立連接即可。用于清除設備在極端情況掉線(斷電、斷網等)后,有一分多鐘在線滯留,在這段時間內無法checkin成功,如果無法接受一分鐘等待,可使用此命令消除滯留,消除后即可登錄。也可用于在其他地方強制目標設備下線。

    M —— 固定(Method)

    checkout —— 固定,強制目標設備下線指令

    ID —— 固定
    xx1 —— 可變,設備ID,在會員中心查看
    K —— 固定(apiKey)
    xx2 —— 可變,設備apikey,在會員中心查看

    發送命令端返回結果

    說明:發送頻率過快或apikey錯誤無返回,目標設備不在線無返回。

    {"M":"checkout","ID":"xx1","T":"xx2"}\n

    M —— 固定(Method)

    checkout —— 固定,強制目標設備下線成功返回指令

    ID —— 固定
    xx1 —— 可變,成功下線設備ID,可在會員中心查看

    T —— 固定(time)
    xx2—— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數

    被強制下線設備在下線前收到信息

    {"M":"checkout","IP":"xx1","T":"xx2"}\n

    說明:可根據此命令判斷是否人為強制下線,從而決定是否需要繼續自動重連、登錄。

    M —— 固定(Method)

    checkout —— 固定,強制目標設備下線成功返回指令

    IP —— 固定
    xx1 —— 可變,發送強制命令設備IP地址

    T —— 固定(time)
    xx2—— 可變,服務器發送信息時的時間戳,自從 Unix 紀元(格林威治時間 1970 年 1 月 1 日 00:00:00)到當前時間的秒數

    五、PC端模擬測試

    PC模擬測試TCP長連接教程見:《貝殼物聯通訊協議TCP連接測試教程

    Windows測試工具見:http://www.smgyp.com/talk/1140.html

    六、用戶相關指令

    用戶相關指令另起一章說明,詳見:《貝殼物聯用戶通訊協議


    上一篇:沒有了
    下一篇:遠程控制通訊——基于Arduino + ESP8266控制LED燈并返回控制結果
    返回頂部
    国产福利91精品一区二区三区