【话题】自己开发网页监控PLC，你敢么？ （20160126）

一．系统简介
GRM 云服务器提供多种不同的接口以访问 GRM 设备中的数据。各种接口的优缺点见下表：
本文档描述的是 Web 数据接口。 另外两种接口（内置网页系统和 OPC Server） 在本文档中不涉及。Web 数据接口对于每个 GRM 设备默认是不开通的， 需要开通该功能的请与我们联系。
登录的动作
客户端需要 2 步骤动作： 第一步是在主服务器上登录， 得到一个代表该设备的 Session ID（以后简称 SID），以及该设备对应的数据服务器的地址。 第二步是在数据服务器上用 SID 来做读写操作。SID 是一个 64 位的随机数， 它是客户端能够访问这个 GRM 设备的唯一凭据。 客户端的 IP 地址可能随时变化，只要拥有正确的 SID 就可以跟设备通讯。 在不同的设备之间传递 SID 也是可以的。 例如， 客户自己的服务器到 GRM 服务器来登录， 得到 SID， 然后把 SID 传给手机 APP 程序， 这样手机 APP 程序就可以在不知道 GRM设备密码的情况下读写数据了。每个 Session 只要每隔 10 分钟有至少 1 次数据读或写操作， 这个 SID 就会一致有效， 而如果在连续 10 分钟内没有发生任何数据读写操作， 这个 SID 就自 动被服务器删除。 偶尔如果遇到服务器程序维护重启， 所有已登录的 Session 都会丢失。 如果读写操作返回了错误 8， 表示服务器认为这个 SessionID 是无效的， 请重新登录
一次（不论是什么原因。有可能是 SID 超时被删掉， 也可能是服务器重启）。因为服务器上的每个 Session 需要占用一定的系统资源， 系统给每个 GRM 设备分配的 Session 数目 限制为100 个。如果您在 10 分钟之内登录超过 100 次， 将得到错误 15， 您只能等到某个旧的 SID 在 10 分钟后被删掉，然后才能登录上（客户对于不想使用的 SID 没有办法明确的删除， 只能等 10 分钟超时自动删掉）。我们的主服务器是固定的地网址http://www.yunplc.com:7080（如果客户自行搭建主服务器， 请向服务器提供商索取地址）， 数据服务器有多个， 具体某个 GRM 设备属于哪个数据服务器由登录命令返回。 如果有多个客户端连接到同一个 GRM 设备， 这些客户端会得到同样的数据服务器。
如果没有任何客户端访问， GRM 设备端不会有数据流量，只有心跳数据包以便维持 GPRS 连接。 此时一个月 只消耗几兆的流量。只要有任何客户端连接到云服务器，不论是服务器支持的三种接口（内置网页系统， Web数据接口， OPC Server） 中的哪一种， 数据服务器都会自 动启动到 GRM 设备的读操作。 所有客户端的读都被数据服务器缓冲。不论有多少个客户端，到 GRM 设备的读流量只有 1 份。 但是写操作是不缓冲的， 如果多个客户端从不同的入口都来写同一个 GRM 设备变量，后发出的写会覆盖之前的写的结果， 导致只有最后一个写有效。 客户需要自行避免其中的冲突问题。
4
客户端登录的推荐作法
如果客户自己做网站来从我们服务器获取数据， 请特别注意： 不要在每次 Web 客户请求页面的时候登录。
这样会严重影响系统性能！如果负载量不大， 可以在 Web 客户登录您的网站的时候来登录， 然后保存 SID 供以后的数据访问来使用。也就是您的每个 Web 客户占用一个我们服务器的 SID。 因为每个设备只能并行登录 100 个 SID， 这样就限制了您的网站每个设备只能同时连接 100 个 Web 客户。对于手机程序（安卓或 IOS）， 通常也使用这种方法。 这样就不需要额外的服务器了， 每个手机程序都是直接连接到我们数据服务器的。一般来说同时上线 100 个手机已经足够用了。 如果您要同时上线更多的手机， 仍然得用下面的做法， 通过自己的一个服务器来缓存数据。更好的做法是：用客户网站的 Web 服务器自身作为数据缓存。 也就是说， 在有 Web 用户登录到客户网站的时候，客户的 Web 服务器到我们服务器登录一次（对每个设备只需要登陆这一次！）， 然后用单独的一个线程或者定时器， 定时读取该设备的全部变量， 缓存起来。用户的所有网页请求都从 Web 服务器的缓存里面直接获取数据。 客户端如果要写入变量， 也是由网页首先提交到 Web 服务器的缓存里面（以保证其他的用户的页面能立刻看到）， 然后再排队，用 Web 服务器自己的 SID 写到我们数据服务器。（后面 3.4 节有推荐的流程）因为一个 GRM 设备上只有一份数据， 在每个 Web 客户请求页面的时候从我们数据服务器读取一次是没有意义的，只会减慢您的 Web 服务器的响应时间。在每个 Web 客户请求页面的时候都登录一个 SID 是错误的作法！ 注意每个 GRM 设备同时只能登录 100 个
SID。如果每次登录一个 SID 用过就扔掉， 很快您的网站就无法再登录了！
Web 服务器自 己去读全部数据并缓存起来是更有效的做法。 读全部数据只有第一次需要带所有变量名， 以后都可以用[重复上次读]命令。注意， 每个 SID 只有一个读命令缓存。 如果客户 A 用一个 SID 发出某种方式的读， 然后就开始使用  [重复上次读]命令以节约流量， 而客户 B 也用这个 SID 发出了另一个不同的读命令， 那么客户 A 的“重复上次读” 就会读到错误的结果（变成了重复 B 的读命令结果）。
二．客户端操作命令说明
客户端所有的操作命令都是 HTTP 的 POST 动作。 POST 请求里面的必备部分只需要 Host 和 Content-Length，其他 HTTP 头选项均不被服务器识别， 也无意义。 POST 请求里面的 Content-Type 实际被服务器强制当作 ”text/plain;charset=UTF-8”， 也就是无格式的 UTF-8 纯文本。 客户端指定其他任何 Content-Type 均无效。 数据区永远是 UTF8 编码的(如果有中文， 请特别注意编码！ )。 数据区如果有多行， 两行之间的分隔符是回车换行\r\n
（也就是十六进制的 0x0D 和 0x0A， 或者十进制的 13 和 10）。 变量名的英文是不区分大小写的。因为网页上 FORM 的默认 POST 类型是”application/x-www-form-urlencoded”， 如果您的编程语言默认 POST类型是这个， 请一定要记得修改类型。 把类型改成”text/plain;charset=UTF-8”。否则您的编程语言有可能自 动把数据内容做 UrlEncode 编码， 结果数据里面的中文变量名和两行中间的回车换行符就会被编码成%xx 的格式，导致服务器无法识别。
1.[登录]
该命令用于客户端到主服务器登录， 以得到 SID 和数据服务器地址。
请求内容中的 GRM=xxxxxx 就是 GRM 设备的序号（ 11 位数字）， PASS=xxxxxx 就是 GRM 设备的密码。
返回值有 3 行， 第一行 OK 或者 ERROR 表示成功还是出错， 如果出错会有错误码和描述。
ADDR=xxxx:xx， 冒号前面的部分是数据服务器的地址，后面的部分是数据服务器的端口。
2.[读变量]
该命令用于客户端从数据服务器读指定的变量值，同时更新服务器内部的读命令缓存。
3.[重复上次读]
该命令的 URL 和返回内容都与[读变量]命令完全相同， 唯一的区别是请求内容为空白。 效果相当于使用了
服务器读命令缓存里面的读请求内容。 这样可以明显节约客户端流量。
4.[写变量]
该命令用于客户端从数据服务器写指定的变量值。
5.[枚举变量信息]
该命令用于客户端从数据服务器枚举设备中的变量信息
注意事项:
变量组名 G 和 Web 变量描述 C， 这两个选项的内容都可能是空白。 如果某一项是空白， 它跟后面一项之间的逗号分隔符仍然存在， 因此只要查找逗号来拆分各个选项的内容就可以了。因为 Web 变量描述的内容可能含有逗号， 为了防止解析逗号的时候出现混乱， 尽量不要指定 C 选项。如果确实需要获取 Web 变量描述， 请把 C 选项放在最后。 这样在处理了前面几个逗号以后， 最后剩下的部分都是 Web 变量描述了。或者先用 NTRPG 选项请求一次， 每行的内容正常按照逗号来拆分； 再用 C 选项请求一次， 直接得到每行只有 Web 变量描述， 这样就不需要处理逗号了。
6.[读基站定位信息]
该命令用于客户端从数据服务器读取设备的基站定位信息
注意事项:
1. 这里得到的经纬度坐标都是百度地图上的坐标， 该坐标值与 GPS 真实坐标有差别（国家测绘局规定中国境内
的地图不得使用真实 GPS 坐标）。 我们推荐客户使用百度地图来显示位置。 如果您要使用其他地图软件， 请自
行转换坐标。
2. 某些偏远地区可能没有区/县， 乡镇/街道和临近标志点， 此时这些没有的内容都是空白， 但尾部换行符保留。
3. 基站原始数据的格式为（每个数据项之间用分号来分隔）：
基站数目 ;移动国家码 MCC;移动运营商码 MNC;后面每个基站有 3 个数据， 依次是 LAC;CID;信号强度 RSSI;
l LAC 和 CID 是以十六进制表示的， 都是 4 个字符， 也就是 16 位数字。
l 其他参数都是十进制的数字。
l 基站数目 最多可能有 7 个。
l RSSI 的范围是 0 到 63。
l 这些原始数据主要是供客户自 己执行基站定位算法所用， 如果客户直接使用我们的基站定位结果， 就不需
要解析这些原始数据
4. 基站定位的精度大约在 100 米到 1 公里之间。 在城市里， 基站比较密集的时候可以到 100 米级别的精度，如
果在偏远地方， 基站非常稀少， 精度可能降低到 1 公里级别。
5. 基站位置无法查到的原因， 可能是运营商新建的基站， 或者该位置太偏远， 我们的基站信息提供商还没有收
录。 此时如果您自 己有更好的基站信息提供商， 也可以自行解析基站数据来定位。
6. 如果设备不支持基站定位功能（例如设备配置中没有打开地图定位功能， 或者是旧版本的固件无此功能），
会返回错误码 5（设备不支持此功能）。 对于旧版本固件不支持基站定位的， 可以联系我们客服， 获取新版本固
件来升级。
三． 编程调试中需要注意的一些地方
1.网页界面上的系统变量名称转换
为了方便调试,很多网页开发者使用我们内置的网页系统来查看变量名和对应的值， 但是我们网页上显示的
系统变量的变量名是经过转换的。下面是全部系统变量的转换对应表（因为变量名不区分大小写，所以任何大
小写形式的系统变量名都可以识别）：
作法流程
1) 客户服务器收到用户的网页请求
2) 客户服务器到 GRM 服务器登录， 获取一个 SID
3) 客户服务器用这个 SID 到 GRM 数据服务器读取本次网页需要的数据
4) 客户服务器生成网页， 送给网页用户
5) 这个 SID 扔掉， 再也不使用。 遇到下一个网页请求， 从步骤 1) 重新开始
4.推荐的最佳作法流程
除了网页生成逻辑以外，对每个 GRM 设备有一个独立的“变量读取器” 模块， 该模块里面有：
l 登录得到的当前有效 SID
l 变量缓存， 包括设备中的所有变量名和对应的变量值
l 写变量队列， 保存所有从网页发来的写操作
l 网页最近使用时间（方便知道什么时候没人使用网页了，不需要再读取）， 但如果需要记录历史数据就不
需要最后使用时间， 因为必须不停的读，不然就没有历史数据了。
变量读取器的内部流程：
1) 到 GRM 服务器登录，得到 SID
2) 用这个 SID 定时读取 GRM 设备的全部变量（第一次是正常读； 以后都用重复读命令，无需变量名）
3) 读到的变量放在自 己的缓存里面， 供生成页面的时候使用。
4) 如果写变量队列里面有内容， 就发出 GRM 的写命令， 把数据写到 GRM 数据服务器
5) 不论读或写， 如果见到错误码(常见的是错误 8，表示上次登录的 SID 已经过期)， 就重新跳到步骤 1) 来登
录，否则继续定时读/写
6) 如果网页最近使用时间距离现在已经超过一定时间（例如半个小时，或者你们自 己愿意的某个时间），表
示很久都没有人使用网页了，不需要再读了。 停止变量读取器， 以便停止 GPRS 流量。
网页生成逻辑的内部流程：
1) 客户服务器收到用户的网页请求
2) 检查服务器内部的变量读取器是否启动， 如果没有就启动变量读取器
3) 从变量读取器中得到数据的最新值， 生成网页， 送给网页用户。同时更新网页最近使用时间。
4) 如果网页有写操作， 把变量名和对应的值加入到变量读取器的写变量队列， 并且写入变量缓存。
5.低流量网站的作法流程（手机程序也可以这样做）
1) Web 用户在网站登录的时候， 网站服务器到 GRM 服务器登录，得到 SID 与该用户关联。
2) 该客户的每次网页请求， 都用这个 SID 到 GRM 服务器做一次数据读， 得到数据来生成网页。
3) 如果网页有写操作， 也用这个 SID 发出写命令。
4) 如果某一次读或写返回错误码， 发现这个 SID 已经过期， 就重新登录一次。

四． 程序返回的错误码和错误描述汇总

项目也有，慢慢的，我会展示给大伙