Skip to content

Commit c6d6939

Browse files
JhosuaSparrowJhosuaSparrow
committed
update: ZH docs.
1 parent 596ad4e commit c6d6939

3 files changed

Lines changed: 107 additions & 199 deletions

File tree

‎README_ZH.md‎

Lines changed: 4 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -4,190 +4,18 @@
44

55
## 简介
66

7-
当前项目基于 QuecPython 语言开发。
7+
AIS-140，全称 AUTOMOTIVE INDUSTRY STANDARD，汽车行业标准，是印度制定的一套针对车载卫星定位系统的通信协议。该协议主要用于道路车辆的卫星定位设备与后台监控中心之间的数据通讯，支持车辆定位、跟踪、应急救援等功能。它由印度汽车工业标准委员会 (AISC) 制定，印度汽车研究协会（ARAI）发布，是印度智能交通系统（ITS）的重要组成部分。
8+
9+
本项目基于 QuecPython 语言开发。
810

911
目前支持的版本为 AIS-140 (2016)。
1012

1113
该库的目的是提供构建车辆位置跟踪和紧急按钮的构建块。 **该库不提供完整的解决方案，因为任何实现都是特定于其预期用途的**。该库中的文档提供了有关如何最好地构建完整解决方案的指导。
1214

13-
**注意:**
14-
15-
> 要运行这些示例，需要依赖项 usocket 模块!
16-
17-
## 车辆定位跟踪和紧急按钮
18-
19-
`demo/ais_client_demo.py` 是一个车辆位置跟踪和紧急按钮演示。
20-
21-
```python
22-
from usr.ais import AISClient
23-
24-
# Receive Server Commands Funtion.
25-
def server_cmd(cmd, key, val):
26-
"""This function is for receiving server commands.
27-
28-
Args:
29-
cmd(str): SET/GET/CLR.
30-
key(str):
31-
PIP - Primary Server IP
32-
PPT - Primary Server Port
33-
SIP - Secondary Server IP
34-
SPT - Secondary Server Port
35-
EO - Emergency OFF
36-
ED - Emergency Duration
37-
APN - Network APN
38-
SL - Speed Limit
39-
VN - Vehicle Registration Number
40-
UR - Update Rate
41-
URE - Update Rate Emergency
42-
URH - Update Rate Health Packet
43-
VID - Vendor ID
44-
ODM - Set Odometer
45-
val(str): Value of commmand key.
46-
"""
47-
print("cmd[%s], key[%s], val[%s]" % (cmd, key, val))
48-
49-
50-
def main():
51-
# Init AIS Client.
52-
cfg = {
53-
"ip": "xxx.xxx.xxx.xxx",
54-
"port": 9000,
55-
}
56-
ais_client = AISClient(**cfg)
57-
ais_client.set_callback(server_cmd)
58-
59-
# Connect Server
60-
res = ais_client.connect()
61-
62-
# Send Login Packet
63-
login_kwargs = {...}
64-
res = ais_client.send_login(**login_kwargs)
65-
print("ais_client.send_login() %s" % res)
66-
67-
# Send Health Monitoring Packet
68-
hbt_kwargs = {...}
69-
res = ais_client.send_health_monitoring(**hbt_kwargs)
70-
print("ais_client.send_health_monitoring() %s" % res)
71-
72-
# Send Location/Alert Information Packet
73-
lai_kwargs = {...}
74-
res = ais_client.send_loction_alert_information(**lai_kwargs)
75-
print("ais_client.send_loction_alert_information() %s" % res)
76-
77-
# Send Emergency Packet
78-
meg_kwargs = {...}
79-
res = ais_client.send_emergency(**meg_kwargs)
80-
print("ais_client.send_emergency() %s" % res)
81-
82-
# Disconnect Server
83-
res = ais_client.disconnect()
84-
print("ais_client.disconnect() %s" % res)
85-
```
86-
87-
## 项目文件说明
88-
89-
```shell
90-
|-- code
91-
|-- ais.py
92-
|-- logging.py
93-
|-- demo
94-
|-- ais_client_demo.py
95-
|-- ais_server_demo.py
96-
|-- docs
97-
|-- en
98-
|-- API_Reference.md
99-
|-- zh
100-
|-- API参考手册.md
101-
|-- AIS-140 (2016).pdf
102-
```
103-
104-
- `code` 该目录包含了 AIS 客户端代码。
105-
- `code/ais.py` 该文件包含了所有 AIS 客户端请求接口.
106-
- `code/logging.py` 该文件为日志模块.
107-
- `demo` 该目录包含了 AIS 客户端样例和 AIS 服务器样例.
108-
- `demo/ais_client_demo.py` 该文件是一个基于 QuecPython 的 AIS 客户端样例.
109-
- `demo/ais_server_demo.py` 该文件是一个基于 CPython 的 AIS 服务端样例.
110-
- `docs` 该目录包含了 AIS-140 协议相关文档和 API 参考手册.
111-
112-
## 如何使用
113-
114-
### 运行 AIS-140 服务
115-
116-
> 如果您有自己的 AIS-140 服务器，则可以跳过此说明。
117-
118-
#### 1. 安装环境
119-
120-
- 操作系统: Window or Linux.
121-
122-
- 语言: Python (Python-3.11.2).
123-
124-
#### 2. 配置服务器并运行样例
125-
126-
- 在 `demo/ais_server_demo.py` 文件中修改你的服务器端口.
127-
128-
```python
129-
SERVER_PORT = 31500 # 修改为你自己的服务的端口
130-
...
131-
132-
if __name__ == '__main__':
133-
try:
134-
logging.info("Start Server !")
135-
socket_serve = TCPServer(('', SERVER_PORT), ReceiveHandler)
136-
for i in range(THREAD_WORKERS_NUM):
137-
t = Thread(target=socket_serve.serve_forever)
138-
t.daemon = True
139-
t.start()
140-
socket_serve.serve_forever()
141-
except KeyboardInterrupt:
142-
socket_serve.shutdown()
143-
logging.info("Stop Server !")
144-
```
145-
146-
- 运行 `python demo/ais_server_demo.py` 文件. 当看到交互输出 `[INFO] xxxx-xx-xxx xxx xx:xx:xx ais_server_demo.py: Start Server !`, 则服务端已经正常启动。
147-
148-
```shell
149-
>>> python ais_server_demo.py
150-
[INFO] xxxx-xx-xxx xxx xx:xx:xx ais_server_demo.py: Start Server !
151-
```
152-
153-
### 运行 AIS-140 客户端
154-
155-
#### 1. 运行环境
156-
157-
您需要使用我们的 QuecPython 模块。
158-
159-
#### 2. 配置客户端并运行样例
160-
161-
- 在 `demo/ais_client_demo.py` 文件中配置服务器ip和端口。
162-
163-
```python
164-
if __name__ == "__main__":
165-
# Init AIS Client.
166-
cfg = {
167-
"ip": "xxx.xxx.xxx.xxx",
168-
"port": 9000,
169-
} # Use your own server ip and port.
170-
ais_client = AISClient(**cfg)
171-
ais_client.set_callback(server_cmd)
172-
```
173-
174-
- 将代码下载到 QuecPython 模块
175-
176-
**注意:**
177-
178-
> 如何下载 python 代码并在 QuecPython 模块中运行 python demo 可参考 [QuecPython 文档中心](https://python.quectel.com/doc/Getting_started/en/index.html)。
179-
180-
您可以将完整的 `code` 目录代码 和 `demo/ais_client_demo.py` 下载到我们的 QuecPython 模块，并运行 `ais_client_demo.py` 来测试 AIS-140 车辆位置跟踪和紧急按钮。
181-
182-
你可以在 QPYcom工具的交互界面看到日志 `ais_client.send_login() True.`, 则 `Login Packet` 消息报已经发送到服务器端.
183-
184-
**注意:**
185-
186-
> 您可以参考`demo/ais_client_demo.py`来编写符合业务逻辑的客户端请求。
187-
18815
## 用法
18916

19017
- [API 参考手册](./docs/zh/API参考手册.md)
18+
- [用户使用手册](./docs/zh/用户使用手册.md)
19119
- [客户端示例代码](./demo/ais_client_demo.py)
19220
- [服务端示例代码](./demo/ais_server_demo.py)
19321

‎docs/zh/API参考手册.md‎

Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,10 @@ res = ais_client.set_callback(server_cmd)
6161
|key|str|指令标识：<br>`PIP` - 主服务器 IP（主服务器IP或域名）<br>`PPT` - 主服务器端口<br>`SIP` - 辅助服务器 IP（辅助服务器IP或域名）<br>`SPT` - 辅助服务器端口<br>`EO` - 紧急关闭（紧急关闭或停止紧急消息。仅允许使用此键进行设置。）<br>`ED` - 紧急情况持续时间（紧急超时持续时间以分钟为单位。）<br>`APN` - 网络 APN（网络接入点名称）<br>`SL` - 速度限制（速度限制以公里/小时为单位）<br>`VN` - 车辆登记号码<br>`UR` - 更新频率（车辆行驶时更新持续时间/数据速率（以秒为单位）。）<br>`URE` - 报警更新频率（更新紧急数据包的持续时间或数据速率（以秒为单位）。）<br>`URH` - 健康监控数据包更新频率（健康监控数据包的更新持续时间或数据速率（以分钟为单位）。）<br>`VID` - 供应商 ID<br>`ODM` - 设置里程表（该命令可用于重置里程表或将里程表设置为一个值。该值以公里为单位，可以是浮点数。）|
6262
|val|str|指令标识值|
6363

64+
**注意：**
65+
66+
服务器下发的指令内容需要根据实际的服务器协议来确认，不同的服务器有不同的业务指令。
67+
6468
**返回值说明：**
6569

6670
|类型|说明|
@@ -74,7 +78,7 @@ res = ais_client.set_callback(server_cmd)
7478
> 与服务器建立 TCP/UDP 连接。
7579
7680
```python
77-
# Connect Server
81+
# 连接服务器
7882
res = ais_client.connect()
7983
```
8084

@@ -91,7 +95,7 @@ res = ais_client.connect()
9195
> 与服务器断开 TCP/UDP 连接。
9296
9397
```python
94-
# Disconnect Server
98+
# 断开服务器连接
9599
res = ais_client.disconnect()
96100
```
97101

@@ -108,7 +112,7 @@ res = ais_client.disconnect()
108112
> 每当设备与服务器建立新的 TCP 连接时，就会向服务器发送登录数据包。
109113
110114
```python
111-
# Send Login Packet
115+
# 发送登录数据包
112116
login_kwargs = {
113117
"vender_id": "QUECTEL",
114118
"vehicle_reg_no": "car123456",
@@ -129,7 +133,7 @@ res = ais_client.send_login(**login_kwargs)
129133
|:---|:---|:---|
130134
|vender_id|str|供应商 ID|
131135
|vehicle_reg_no|str|车辆登记号|
132-
|imei|str|IMEI号|
136+
|imei|str|IMEI|
133137
|firmware_version|str|固件版本|
134138
|protocal_version|str|协议版本|
135139
|latitude|str|纬度，精确到小数点后 6 位|
@@ -150,7 +154,7 @@ res = ais_client.send_login(**login_kwargs)
150154
> 该数据包定义设备的状态或健康状况。
151155
152156
```python
153-
# Send Health Monitoring Packet
157+
# 发送健康监控数据包
154158
hbt_kwargs = {
155159
"vender_id": "QUECTEL",
156160
"firmware_version": "FIRMWARE_VERSION",
@@ -172,14 +176,14 @@ res = ais_client.send_health_monitoring(**hbt_kwargs)
172176
|:---|:---|:---|
173177
|vender_id|str|供应商 ID|
174178
|firmware_version|str|固件版本|
175-
|imei|str|IMEI号|
179+
|imei|str|IMEI|
176180
|battery_percentage|str|电池电量百分比|
177181
|Low_battery_threshold_value|str|低电报警阈值|
178182
|memory_percentage|str|内存使用百分比|
179183
|data_update_rate_when_ignition_on|int|设备点火时数据上报周期，单位：秒|
180184
|data_update_rate_when_ignition_off|int|设备熄火时数据上报周期，单位：秒|
181185
|digital_io_status|str|数字输入状态：<br>0001 (DIN1 = 0，DIN2 = 0，DIN3 = 0，DIN4 = 1)|
182-
|analog_io_status|float|输入电压值，单位：伏（V）|
186+
|analog_io_status|float|输入电压值，单位：伏特|
183187

184188
**返回值说明：**
185189

@@ -194,7 +198,7 @@ res = ais_client.send_health_monitoring(**hbt_kwargs)
194198
> 这是设备向服务器周期性发送的位置信息包。
195199
196200
```python
197-
# Send Location/Alert Information Packet
201+
# 发送定位或报警数据包
198202
lai_kwargs = {
199203
"vender_id": "QUECTEL",
200204
"firmware_version": "FIRMWARE_VERSION",
@@ -247,39 +251,39 @@ res = ais_client.send_loction_alert_information(**lai_kwargs)
247251
|packet_type|str|详见 [`PacketTypes`](#packettypes) 枚举类型|
248252
|alert_id|str|详见 [`AlertID`](#alertid) 枚举类型|
249253
|packet_status|str|包状态<br>`L` - 实时数据包<br>`H` - 历史数据包|
250-
|imei|str|IMEI号|
254+
|imei|str|IMEI|
251255
|vehicle_reg_no|str|车辆登记号|
252256
|gps_fix|int|GPS 数据是否有效<br>0 - 无效<br>1 - 有效|
253257
|date|str|GPS 日期数据，数据格式：DDMMYYYY（日月年）|
254-
|time|str|GPS 时间数据，数据格式：HHmmss（时分秒）|
258+
|time|str|GPS 时间数据，数据格式：hhmmss（时分秒）|
255259
|latitude|str|纬度，精确到小数点后 6 位|
256260
|latitude_dir|str|纬度方向，N（北）/ S（南）|
257261
|longitude|str|经度，精确到小数点后 6 位|
258262
|longitude_dir|str|经度方向，E（东）/ W（西）|
259-
|speed|float|车辆速度，精确至小数点后 1 位（公里/小时）|
260-
|heading|float|地面航向（以度为单位）|
263+
|speed|float|车辆速度，单位：公里/小时（精确至小数点后 1 位）|
264+
|heading|float|地面航向，单位：度|
261265
|no_of_satellites|int|用于定位的可见卫星数量|
262-
|altitude|int|设备的海拔高度（以米为单位）|
266+
|altitude|int|设备的海拔高度，单位：米|
263267
|pdop|foat|位置精度稀释|
264268
|hdop|float|水平精度衰减|
265269
|operator_name|str|网络运营商名称|
266270
|ignition|int|点火状态<br>0 - 熄火<br>1 - 点火|
267271
|main_power_status|int|主电源状态<br>0 - 车辆电池断开<br>1 - 车辆电池连接|
268-
|main_input_voltage|float|显示源电压的指示器，单位为伏特（最多 1 位小数）|
269-
|internal_battery_voltage|float|电池电量指示器（以伏特为单位）（精确到小数点后 1 位）|
272+
|main_input_voltage|float|显示源电压的指示器，单位：伏特（精确到小数点后 1 位）|
273+
|internal_battery_voltage|float|电池电量指示器，单位：伏特（精确到小数点后 1 位）|
270274
|emergency_status|int|报警状态<br>0 - 报警关<br>1 - 报警开|
271275
|temper_alert|str|防拆报警<br>`O` - 盒子打开<br>`C` - 盒子关闭|
272276
|gsm_strength|int|GSM信号强度，范围 0 ~ 31|
273277
|mcc|int|移动国家代码|
274278
|mnc|int|移动网络代码|
275279
|lac|int|位置区域码|
276280
|cell_id|int|GSM 小区 ID|
277-
|nmr|str|NMR（Network Measurement Report）（网络测量报告）<br>4 个相邻小区的小区 ID、LAC 和信号强度<br>如：`(CELL ID,LAC,GSM STRENGTH)` * 4|
281+
|nmr|str|网络测量报告（Network Measurement Report）<br>4 个相邻小区的小区 ID、LAC 和信号强度<br>如：`(CELL ID,LAC,GSM STRENGTH)` * 4|
278282
|digital_input_status|str|4 个数字输入的状态（按顺序）：<br>[DIN3，DIN2，DIN1，DIN0]<br>0 - 关闭，1 - 开启<br>如：`0001`|
279283
|digital_output_status|str|2 个数字输入的状态（按顺序）：<br>[DOUT1，DOUT0]<br>0 - 关闭，1 - 开启<br>如：`01`|
280-
|analog_input_1|float|模拟输入 1 电压（V）|
281-
|analog_input_2|float|模拟输入 2 电压（V）|
282-
|odometer|int|里程表值（米）|
284+
|analog_input_1|float|模拟输入 1 电压，单位：伏特（精确到小数点后 1 位）|
285+
|analog_input_2|float|模拟输入 2 电压，单位：伏特（精确到小数点后 1 位）|
286+
|odometer|int|里程表值，单位：米|
283287

284288
**返回值说明：**
285289

@@ -294,7 +298,7 @@ res = ais_client.send_loction_alert_information(**lai_kwargs)
294298
> 当设备紧急按键被触发时，则开始上报该紧急报警数据包
295299
296300
```python
297-
# Send Emergency Packet
301+
# 发送紧急报警数据包
298302
meg_kwargs = {
299303
"vender_id": "QUECTEL",
300304
"packet_type": "EMR",
@@ -322,16 +326,16 @@ res = ais_client.send_emergency(**meg_kwargs)
322326
|:---|:---|:---|
323327
|vender_id|str|供应商 ID|
324328
|packet_type|str|紧急数据包类型<br>`EMR` - 紧急呼救信号<br>`SEM` - 停止讯息|
325-
|imei|str|IMEI号|
329+
|imei|str|IMEI|
326330
|packet_status|str|数据包状态<br>`NM` - 普通数据包<br>`SP` - 存储数据包|
327331
|date_time|str|GPS 日期时间值，数据格式：DDMMYYYYHHmmss（日月年时分秒）|
328332
|gps_fix|str|GPS 数据是否有效<br>`V` - 无效<br>`A` - 有效|
329333
|latitude|str|纬度，精确到小数点后 6 位|
330334
|latitude_dir|str|纬度方向，N（北）/ S（南）|
331335
|longitude|str|经度，精确到小数点后 6 位|
332336
|longitude_dir|str|经度方向，E（东）/ W（西）|
333-
|altitude|int|设备的海拔高度（以米为单位）|
334-
|speed|float|车辆速度，精确至小数点后 1 位（公里/小时）|
337+
|altitude|int|设备的海拔高度，单位：米|
338+
|speed|float|车辆速度，单位：公里/小时（精确至小数点后 1 位）|
335339
|distance|int|根据之前的 GPS 数据计算出的距离|
336340
|provider|str|`G` - 来自 GPS 精确定位<br>`N` - 粗略 GPS 或 基站定位数据|
337341
|vehicle_reg_no|str|车辆登记号|

0 commit comments

Comments
 (0)