貝殼物聯平臺通訊協議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協議為基礎的通訊,設備可不必保持在線,隨時在需要的時候向服務器發送指令進行相關操作。
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。
{"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)到當前時間的秒數。
{"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是為維度值,詳見:定位數據上傳說明。
{"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)到當前時間的秒數。
{"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)到當前時間的秒數
{"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"
{"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)到當前時間的秒數
{"M":"status"}\n
說明:(兩次查詢間隔不得小于10s)
M —— 固定(Method)
status —— 固定,查詢當前設備狀態指令(可用 t 代替 status,減小命令長度)
返回結果:
{"M":"xx1"}\n
M —— 固定(Method)
xx1 —— 可變(connected/checked),當前設備狀態,connected代表已連接服務器尚未登錄,checked代表已連接且登錄成功
{"M":"alert","ID":"xx1","C":"xx2"}\n
說明:(設備主動發送報警信息,通過觸發已在用戶中心設置的報警提示,可通過郵件、微博、釘釘機器人、微信(方糖)、webhook等方式,對外發送指定提示內容。兩次發送間隔不得小于10min,無返回)
M —— 固定(Method)
alert —— 固定,設備主動發送報警指令
ID —— 固定
xx1 —— 可變,要觸發的報警提示ID,可在用戶中心查看或添加。
C —— 固定(Content)
xx1 —— 可變,自定義的報警內容。
{"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 —— 可變,根據查詢格式返回服務器的時間
{"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模擬測試TCP長連接教程見:《貝殼物聯通訊協議TCP連接測試教程》
Windows測試工具見:http://www.smgyp.com/talk/1140.html
用戶相關指令另起一章說明,詳見:《貝殼物聯用戶通訊協議》