From 05fa4a8ed69381537f817c7413664b4cebddfee7 Mon Sep 17 00:00:00 2001 From: Rich Date: Thu, 16 Feb 2023 15:16:41 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E7=89=88Wiki=E6=96=87=E6=A1=A3atcmd/s?= =?UTF-8?q?im/sms/cellLocator/wifiLocator/net/voiceCall=E6=A8=A1=E5=9D=97?= =?UTF-8?q?=E4=B8=AD=E6=96=87=E6=96=87=E6=A1=A3=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../atcmd.md" | 48 + .../cellLocator.md" | 56 + .../net.md" | 1041 +++++++++++++++++ .../sim.md" | 603 ++++++++++ .../sms.md" | 452 +++++++ .../voiceCall.md" | 684 +++++++++++ .../wifilocator.md" | 68 ++ 7 files changed, 2952 insertions(+) create mode 100644 "docs/API_reference/zh/QuecPython\347\261\273\345\272\223/net.md" create mode 100644 "docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sim.md" create mode 100644 "docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sms.md" create mode 100644 "docs/API_reference/zh/QuecPython\347\261\273\345\272\223/voiceCall.md" diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/atcmd.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/atcmd.md" index e69de29b..8fd57d7b 100644 --- "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/atcmd.md" +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/atcmd.md" @@ -0,0 +1,48 @@ +# `atcmd` - 发送AT指令功能 + +提供发送AT指令的方法，使模组能够通过Python代码发送AT指令。 + +## 方法 + +### `atcmd.sendSync` + +``` +atcmd.sendSync(atcmd,resp,include_str,timeout) +``` + +该方法用于对模组发送AT指令。 + +**参数描述：** + +* `atcmd` - 需要发送的AT指令，字符串类型，必须包含'\r\n'。 +* `resp` - AT指令返回的字符串内容，字符串类型。 +* `include_str` - 关键字，字符串类型，具体作用见下表： + +| 值 | 含义 | +| ---------- | ------------------------------------------------------------ | +| `空字符串` | 获取AT指令返回的所有数据(不包含‘OK’等结果性的字符数据)放入`resp`参数中 | +| `不为空` | 筛选包含关键字的数据放入`resp`参数中。 | + +* `timeout` - 超时时间，整型值，单位/秒。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`非0`表示失败。 + +**示例：** + +```python +>>> import atcmd +>>> resp=bytearray(50) +>>> atcmd.sendSync('at+cpin?\r\n',resp,'',20) +0 +>>> print(resp) +bytearray(b'\r\n+CPIN: READY\r\n\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00 +\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') + +atcmd.sendSync('at+cpin\r\n',resp,'',20) +1 +>>> print(resp) +bytearray(b'\r\nERROR\r\n\n +\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/cellLocator.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/cellLocator.md" index e69de29b..a969b440 100644 --- "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/cellLocator.md" +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/cellLocator.md" @@ -0,0 +1,56 @@ +# `cellLocator` - 基站定位 + +`cellLocator` 提供基站定位功能，获取模组经纬度坐标信息。 + +>注意：当前仅EC600S/EC600N/EC800N/EC200U/EC600U系列支持该功能。 + +## 方法 + +### `cellLocator.getLocation` + +```python +cellLocator.getLocation(serverAddr, port, token, timeout, profileIdx) +``` + +该方法用于获取模组经纬度坐标信息。 + +**参数描述：** + +* `serverAddr` - 服务器域名，字符串类型，长度必须小于255 bytes，目前仅支持 “[www.queclocator.com”](http://www.queclocator.xn--com-9o0a/) +* `port` - 服务器端口，整型值，目前仅支持 80 端口 +* `token` - 密钥，字符串类型，16位字符组成，需要申请 +* `timeout` -设置超时时间，整型值，范围1-300s，默认300s +* `profileIdx` - PDP上下文ID，整型值，一般设置为1，设置其他值可能需要专用apn与密码才能设置成功；范围如下：
EC600N/EC600S/EC800N，范围：1~8
EC200U/EC600U，范围：1~7 + +**返回值描述：** + + 成功返回经纬度坐标信息，元组格式：`(longtitude, latitude, accuracy)`，`(0.0, 0.0, 0)`表示未获取到有效坐标信息； + +`longtitude` ： 经度 + +`latitude` ：纬度 + +`accuracy` ：精确度，单位米 + +失败返回错误码说明如下： + +`1` – 初始化失败 + +`2` – 服务器地址过长（超过255字节） + +`3` – 密钥长度错误，必须为16字节 + +`4` – 超时时长超出范围，支持的范围（1 ~ 300）s + +`5` – 指定的PDP网络未连接，请确认PDP是否正确 + +`6` – 获取坐标出错； + +**示例：** + +```python +>>> import cellLocator +>>> cellLocator.getLocation("www.queclocator.com", 80, "xxxxxxxxxxxxxxxx", 8, 1) +(117.1138, 31.82279, 550) +# 上面使用的密钥"xxxxxxxxxxxxxxxx"指代token，具体需要向移远申请 +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/net.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/net.md" new file mode 100644 index 00000000..554fb122 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/net.md" @@ -0,0 +1,1041 @@ +# `net` - 网络相关功能 + +`net`模块包含了模组网络相关的功能，提供配置和查询网络模式信息等接口，比如获取注网状态，设置搜网模式等。 + +>注： +>建议用户使用不同运营商的SIM卡时，则配置对应运营商的APN信息；如果不配置或者配置错误，可能会导致模组无法注网。用户具体如何配置APN信息，参考`dataCall.setApn`方法。 + +## 方法 + +### `net.csqQueryPoll` + +```python +net.csqQueryPoll() +``` + +该方法用于获取csq信号强度。 + +**参数描述：** + +* 无 + +**返回值描述：** + + 成功返回整型的csq信号强度值，失败返回整型值`-1`，返回值为`99`表示异常； + +>信号强度值范围0 ~ 31，值越大表示信号强度越好。 + +**示例：** + +```python +>>> import net +>>> net.csqQueryPoll() +31 +``` + + + +### `net.getCellInfo` + +```python +net.getCellInfo([sinrEnable]) +``` + +该方法用于获取邻近小区的信息。 + +**参数：** + +* `sinrEnable` - 使能是否获取sinr数值，整型值，取值范围见下表： + +| 取值 | 含义 | +|-----| ------------- | +| 0 | 不获取sinr数值 | +| 1 | 获取sinr数值 | + + +**返回值：** + + 失败返回整型值`-1`，成功返回包含三种网络系统`（GSM、UMTS、LTE）`的信息的list，如果对应网络系统信息为空，则返回空的List。格式和说明如下： + + `([(flag, cid, mcc, mnc, lac, arfcn, bsic, rssi)], [(flag, cid, licd, mcc, mnc, lac, uarfcn, psc, rssi)], [(flag, cid, mcc, mnc, pci, tac, earfcn, rssi, rsrq, sinr),...])` + +* `GSM`网络系统返回值说明 + +| 参数 | 参数意义 | +| ------- | ------------------------------------------------------------ | +| `flag` | 小区类型，范围0 - 3， 0：当前服务小区，1：邻区，2：同频邻区 ，3：异频邻区 | +| `cid` | 返回GSM网络下的cell id信息，0则为空，范围0 ~ 65535 | +| `mcc` | 移动设备国家代码，范围 0 ~ 999
注意：EC100Y/EC600S/EC600N/EC600E/EC800E/EC200A/EC600M/EC800M系列的模组，该值是用十六进制来表示，比如下面示例中的十进制数1120，用十六进制表示为0x460，表示移动设备国家代码460，其他型号模组，该值直接用十进制表示，比如移动设备国家代码460，就是用十进制的460来表示。 | +| `mnc` | 移动设备网络代码，范围 0 ~ 99 | +| `lac` | 位置区码，范围 1 ~ 65534 | +| `arfcn` | 无线频道编号，范围 0 ~ 65535 | +| `bsic` | 基站识别码，范围 0 ~ 63 | +| `rssi` | GSM网络下，该值表示接收电平，描述接收到信号强度，99表示未知或者无法检测到，该值的计算方式如下：
rssi = RXLEV - 111，单位dBm，RXLEV 的范围是 0 ~ 63，所以rssi范围是 -111 ~ -48 dBm； | + +* `UMTS`网络系统返回值说明 + +| 参数 | 参数意义 | +| -------- | ------------------------------------------------------------ | +| `flag` | 小区类型，范围0 - 3，0：当前服务小区，1：邻区，2：同频邻区 ，3：异频邻区 | +| `cid` | 返回UMTS网络下的 Cell identity 信息，Cell identity = RNC_ID * 65536 + Cell_ID，Cell identity范围 0x0000000 ~ 0xFFFFFFF（注意这里是28bits）；其中RNC_ID的范围是0 ~ 4095，Cell_ID的范围是0 ~ 65535 | +| `lcid` | URA ID，范围 0 ~ 65535，0表示该信息不存在 | +| `mcc` | 移动设备国家代码，范围 0 ~ 999 | +| `mnc` | 移动设备网络代码，范围 0 ~ 99 | +| `lac` | 位置区码，范围 1 ~ 65534 | +| `uarfcn` | 无线频道编号，范围 0 ~ 65535 | +| `psc` | 主扰码，该参数确定所扫描的小区的主要扰码，范围 0 ~ 511 | +| `rssi` | UMTS网络下，该值表示RSCP即CPICH/PCCPCH 接收信号码功率，该值的计算方式如下：
rssi = RSCP - 115，单位dBm ，范围 -121 ~ -25 dBm； | + +* `LTE`网络系统返回值说明 + +| 参数 | 参数意义 | +| ------ | ------------------------------------------------------------ | +| `flag` | 小区类型，范围0 - 3，0：当前服务小区，1：邻区，2：同频邻区 ，3：异频邻区 | +| `cid` | 返回LTE网络下的 Cell identity 信息，Cell identity = RNC_ID * 65536 + Cell_ID，Cell identity范围 0x0000000 ~ 0xFFFFFFF（注意这里是28bits）；其中RNC_ID的范围是0 ~ 4095，Cell_ID的范围是0 ~ 65535 | +| `mcc` | 移动设备国家代码，范围 0 ~ 999 | +| `mnc` | 移动设备网络代码，范围 0 ~ 99 | +| `pci` | 物理层小区标识号，0 ~ 503 | +| `tac` | 跟踪区域码，0 ~ 65535 | +| `earfcn` | 无线频道编号，范围 0 ~ 65535 | +| `rssi` | LTE网络下，表示接收的信号强度，单位dBm，范围 -140 ~ -44 dBm
注：目前除BC25系列和BG77/BG95系列，其它平台均无法获取rssi，显示值使用RSRP代替:
RSRP（负数）= RSRP测量报告值 - 140，单位dBm，范围 -140 ~ -44 dBm | +| `rsrq` |LTE网络参考信号接收质量，范围 -20 ~ -3
注：理论上rsrq的范围应该是-19.5 ~ -3，但由于计算方法问题，目前能给出的是-20 ~ -3
目前仅BC25系列、BG77/BG95系列和EC600E/EC800E系列获取该参数有意义，其它平台该参数无意义| +| `sinr` |信噪比(目前仅BC25系列和EC600E/EC800E系列支持获取该参数）范围-30 ~ 30 | + +>注： +> +>* `sinrEnable`为可选参，不支持的平台可不写，不写默认不获取sinr +> +>* 仅BC25/EC600E/EC800E系列支持获取sinr，其余模组型号均不支持 + +**示例：** + +```python +>>> net.getCellInfo() +([], [], [(0, 232301375, 1120, 17, 378, 26909, 1850, -66, -8), (3, 110110494, 1120, 17, 10, 26909, 2452, -87, -17), (3, 94542859, 1120, 1, 465, 56848, 1650, -75, -10), +(3, 94472037, 1120, 1, 369, 56848, 3745, -84, -20)]) + +//BC25 +>>> net.getCellInfo(1) +([], [], [(0, 17104243, 460, 4, 169, 19472, 3688, -56, -10, -3)]) +>>> net.getCellInfo(0) +([], [], [(0, 17104243, 460, 4, 169, 19472, 3688, -75, -12)]) +>>> net.getCellInfo() +([], [], [(0, 17104243, 460, 4, 121, 19472, 3688, -76, -15)]) +``` + + + +### `net.getConfig` + +```python +net.getConfig() +``` + +该方法用于获取当前网络模式及漫游配置。 + +**参数：** + +* 无 + +**返回值：** + + 失败返回整型值`-1`，成功返回一个元组，包含当前首选的网络制式与漫游打开状态，说明如下： + +* 网络制式 + +| 值 | 网络制式 | +| ---- | ------------------------------------------------------------ | +| 0 | GSM | +| 1 | UMTS | +| 2 | GSM_UMTS（auto） | +| 3 | GSM_UMTS（GSM preferred） | +| 4 | GSM_UMTS（UMTS preferred） | +| 5 | LTE | +| 6 | GSM_LTE（auto） | +| 7 | GSM_LTE（GSM preferred） | +| 8 | GSM_LTE（LTE preferred） | +| 9 | UMTS_LTE（auto） | +| 10 | UMTS_LTE（UMTS preferred） | +| 11 | UMTS_LTE（LTE preferred） | +| 12 | GSM_UMTS_LTE（auto） | +| 13 | GSM_UMTS_LTE（GSM preferred） | +| 14 | GSM_UMTS_LTE（UMTS preferred） | +| 15 | GSM_UMTS_LTE（LTE preferred） | +| 16 | GSM_LTE（dual link） | +| 17 | UMTS_LTE（dual link） | +| 18 | GSM_UMTS_LTE（dual link） | +| 19 | CATM, BG95 supported | +| 20 | GSM_CATM, BG95 supported | +| 21 | CATNB, BG95 supported | +| 22 | GSM_CATNB, BG95 supported | +| 23 | CATM_CATNB, BG95 supported | +| 24 | GSM_CATM_CATNB, BG95 supported | +| 25 | CATM_GSM, BG95 supported | +| 26 | CATNB_GSM, BG95 supported | +| 27 | CATNB_CATM, BG95 supported | +| 28 | GSM_CATNB_CATM, BG95 supported | +| 29 | CATM_GSM_CATNB, BG95 supported | +| 30 | CATM_CATNB_GSM, BG95 supported | +| 31 | CATNB_GSM_CATM, BG95 supported | +| 32 | CATNB_CATM_GSM, BG95 supported | + +>BC25系列不支持此方法 + +**示例：** + +```python +>>>net.getConfig () +(8, False) +``` + + + +### `net.setConfig` + +```python +net.setConfig(mode [, roaming]) +``` + +该方法用于设置网络制式及漫游配置。 + +**参数：** + +* `mode` - 网络制式，整型值，详见上述网络制式表格 + +* `roaming` - 漫游开关，整型值（`0`：关闭， `1`：开启） + +**返回值：** + + 设置成功返回整型值`0`，设置失败返回整型值`-1`。 + +>注意： +> +>* roaming为可选参数，不支持的平台，该参数可不写 +> +>* BC25系列不支持此方法 +> +>* EC200U/EC600U/EG915U系列模组不支持漫游参数配置，且仅支持设置网络制式0/6/8 +> +>* EC600E/EC800E系列模组仅支持LTE ONLY. + +**示例：** + +```python +>>>net.setConfig(6) +0 + +>>>net.getConfig () +(6, False) +``` + + + +### `net.getNetMode` + +```python +net.getNetMode() +``` + +该方法用于获取网络配置模式。 + +**参数：** + +* 无 + +**返回值：** + +失败返回整型值`-1`，成功返回一个元组，格式为：`(selection_mode, mcc, mnc, act)`参数说明如下： + +| 参数 | 类型 | 参数说明 | +| ---------------- | ------ | ------------------------ | +| `selection_mode` | 整型值 | 方式，0 - 自动，1 - 手动 | +| `mcc` | 字符串 | 移动设备国家代码 | +| `mnc` | 字符串 | 移动设备网络代码 | +| `act` | 整型值 | 首选网络的ACT模式 | + +`ACT`模式枚举值参照下表： +| 值 | ACT模式 | +| ---- | ------------------ | +| 0 | GSM | +| 1 | COMPACT | +| 2 | UTRAN | +| 3 | GSM wEGPRS | +| 4 | UTRAN wHSDPA | +| 5 | UTRAN wHSUPA | +| 6 | UTRAN wHSDPA HSUPA | +| 7 | E UTRAN | +| 8 | UTRAN HSPAP | +| 9 | E TRAN A | +| 10 | NONE | + +BG95系列模组`ACT`模式枚举值参照下表： +| 值 | ACT模式 | +| ---- | ------------------ | +| 0 | GSM | +| 1 | GSM COMPACT | +| 2 | UTRAN | +| 3 | GSM wEGPRS | +| 4 | UTRAN wHSDPA | +| 5 | UTRAN wHSUPA | +| 6 | UTRAN wHSDPA HSUPA | +| 7 | E_UTRAN | +| 8 | UTRAN HSPAP | +| 9 | E_UTRAN_CA | +| 10 | E_UTRAN_NBIOT | +| 11 | E_UTRAN_EMTC | +| 12 | NONE | + +**示例：** + +```python +>>> net.getNetMode() +(0, '460', '46', 7) +``` + + + +### `net.getSignal` + +```python +net.getSignal([sinrEnable]) +``` + +该方法用于获取详细信号强度。 + +**参数：** + +* `sinrEnable` - 使能是否获取sinr数值，整型值，取值范围见下表： + +| 取值 | 含义 | +|-----| ------------- | +| 0 | 不获取sinr数值 | +| 1 | 获取sinr数值 | + +**返回值：** + + 失败返回整型值`-1`，成功返回一个元组，包含两个List`(GW 、LTE)`，返回值格式和说明如下： + + `([rssi, bitErrorRate, rscp, ecno], [rssi, rsrp, rsrq, cqi, sinr])` + +* `GSM/WCDMA`返回值参数说明： + +| 参数 | 参数意义 | +| -------------- | ------------------------------------------------------------ | +| `rssi` | GSM和WCDMA网络下，该值表示接收电平，描述接收到信号强度，99表示未知或者无法检测到，该值的计算方式如下
rssi = RXLEV - 111，单位dBm，RXLEV 的范围是 0 ~ 63 | +| `bitErrorRate` | 误码率，范围 0 ~ 7，99表示未知或者无法检测到 | +| `rscp` | 接收信号码功率，范围 -121 ~ -25 dBm，255表示未知或者无法检测到 | +| `ecno` | 导频信道，范围 -24 ~ 0，255表示未知或者无法检测到 | + +* `LTE`返回值参数说明： + +| 参数 | 参数意义 | +| ------ | ------------------------------------------------------------ | +| `rssi` | 接收的信号强度，范围 -140 ~ -44 dBm，99表示未知或者无法检测到 | +| `rsrp` | 下行参考信号的接收功率，范围 -141 ~ -44 dBm，99表示未知或者无法检测到 | +| `rsrq` | 下行特定小区参考信号的接收质量，范围 -20 ~ -3 dBm，值越大越好 | +| `cqi` | 信道质量 | +| `sinr` | 信噪比，BC25系列不支持获取该参数 | + +>注： +> +>* `sinrEnable`为可选参，不支持的平台可不写，不写默认不获取sinr +> +>* BC25系列不支持获取sinr，其余模组型号均支持 + +**示例：** + +```python +>>>net.getSignal() +([99, 99, 255, 255], [-51, -76, -5, 255]) +>>>net.getSignal(0) +([99, 99, 255, 255], [-51, -76, -5, 255]) +>>>net.getSignal(1) +([99, 99, 255, 255], [-51, -76, -5, 255, 18]) +``` + + + +### `net.nitzTime` + +```python +net.nitzTime() +``` + +该方法用于获取当前基站时间。这个时间是基站在模块开机注网成功时下发的时间。 + +**参数：** + +* 无 + +**返回值：** + + 失败返回整型值`-1`，成功返回一个元组，包含基站时间与对应时间戳与闰秒数（0表示不可用），格式为：`(date, abs_time, leap_sec)`，说明如下： + +| 参数 | 类型 | 参数意义 | +| ---------- | ------ | ------------------------------------------------------------ | +| `date` | 字符串 | 基站时间，其中关于时区的部分，不同系列有所区别，具体见示例。
如果需要设置和获取时区，请使用`utime`模块的`setTimeZone(offset)`和`getTimeZone()`接口，
不同平台，这两个接口的单位都是小时，具体参考`utime`模块的说明。 | +| `abs_time` | 整型 | 基站时间的绝对秒数表示 | +| `leap_sec` | 整型 | 闰秒数 | + +**示例：** + +```python +>>> net.nitzTime() +# EC100Y/EC200N/EC600N/EC600S/EC800N/EG912N/EG915N/EC600M/EC800M/EG810M/EC200A系列的返回值，时区单位小时，这里8即表示东八区 +('21/10/26 06:08:03 8 0', 1635228483, 0) +# BC25/EC600E/EC800E/EC200U/EC600U/EG912U/EG915U/EC600G/EC800G系列返回值，时区单位15分钟，这里+32即表示东八区 +('20/11/26 02:13:25 +32 0', 1606356805, 0) +# BG77/BG95系列的返回值，无时区部分 +('23/02/14 02:25:13', 1676312713, 0) +``` + + + +### `net.operatorName` + +```python +net.operatorName() +``` + +该接口用于获取当前注网的运营商信息。 + +**参数：** + +* 无 + +**返回值：** + + 失败返回整型值`-1`，成功返回一个元组，包含注网的运营商信息，格式为： `(long_eons, short_eons, mcc, mnc)`，说明如下： + +| 参数 | 类型 | 参数说明 | +| ------------ | ------ | ---------------- | +| `long_eons` | 字符串 | 运营商信息全称 | +| `short_eons` | 字符串 | 运营商信息简称 | +| `mcc` | 字符串 | 移动设备国家代码 | +| `mnc` | 字符串 | 移动设备网络代码 | + +**示例：** + +```python +>>> net.operatorName() +('CHN-UNICOM', 'UNICOM', '460', '01') +``` + + + +### `net.getState` + +```python +net.getState() +``` + +该接口用于获取当前网络注册信息。 + +**参数：** + +* 无 + +**返回值：** + + 失败返回整型值`-1`，成功返回一个元组，包含电话和网络注册信息，元组中`voice`开头的表示电话注册信息，`data`开头的表示网络注册信息，格式为：`([voice_state, voice_lac, voice_cid, voice_rat, voice_reject_cause, voice_psc], [data_state, data_lac, data_cid, data_rat, data_reject_cause, data_psc])` + +* 返回值参数说明： + + | 参数 | 参数说明 | + | -------------- | ------------------------------------------------------------ | + | `state` | 网络注册状态，具体见下表 | + | `lac` | 位置区码，范围 1 ~ 65534 | + | `cid` | cell id，范围 0x00000000 ~ 0x0FFFFFFF，具体见`net.csqQueryPoll()`中返回值 | + | ``rat`` | 接入技术，access technology，具体见后面表格 | + | `reject_cause` | 注册被拒绝的原因，EC200U/EC600U/BC25系列该参数保留，不作为有效参数 | + | `psc` | 主扰码，Primary Scrambling Code，EC200U/EC600U/BC25系列该参数保留，不作为有效参数 | + +* 网络注册状态`state`枚举值见下表： +| 值 | 状态说明 | +| ---- | ------------------------------------------------------------ | +| 0 | not registered, MT is not currently searching an operator to register to | +| 1 | registered, home network | +| 2 | not registered, but MT is currently trying to attach or searching an operator to register to | +| 3 | registration denied | +| 4 | unknown | +| 5 | registered, roaming | +| 6 | egistered for “SMS only”, home network (not applicable) | +| 7 | registered for “SMS only”, roaming (not applicable) | +| 8 | attached for emergency bearer services only | +| 9 | registered for “CSFB not preferred”, home network (not applicable) | +| 10 | registered for “CSFB not preferred”, roaming (not applicable) | +| 11 | emergency bearer services only | + +* 接入技术`access technology` +| 值 | 说明 | +| ---- | ------------------ | +| 0 | GSM | +| 1 | GSM COMPACT | +| 2 | UTRAN | +| 3 | GSM wEGPRS | +| 4 | UTRAN wHSDPA | +| 5 | UTRAN wHSUPA | +| 6 | UTRAN wHSDPA HSUPA | +| 7 | E_UTRAN | +| 8 | UTRAN HSPAP | +| 9 | E_UTRAN_CA | +| 10 | NONE | + +> 注：BG77/BG95系列参照下表 +> +> | 值 | 说明 | +> | ---- | ------------------ | +> | 0 | GSM | +> | 1 | GSM COMPACT | +> | 2 | UTRAN | +> | 3 | GSM wEGPRS | +> | 4 | UTRAN wHSDPA | +> | 5 | UTRAN wHSUPA | +> | 6 | UTRAN wHSDPA HSUPA | +> | 7 | E_UTRAN | +> | 8 | UTRAN HSPAP | +> | 9 | E_UTRAN_CA | +> | 10 | E_UTRAN_NBIOT | +> | 11 | E_UTRAN_EMTC | +> | 12 | NONE | + + + +**示例：** + +```python +>>> net.getState() +([11, 26909, 232301323, 7, 0, 466], [0, 26909, 232301323, 7, 0, 0]) +``` + + + +### `net.getCi` + +```python +net.getCi() +``` + +该方法用于获取附近小区ID。该接口获取结果即为`net.getCellInfo()`接口获取结果中的cid集合。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回一个list类型的数组，包含小区id，格式为：`[id, ……, id]`。数组成员数量并非固定不变，位置不同、信号强弱不同等都可能导致获取的结果不一样。 + + 失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.getCi() +[14071232, 0] +``` + + + +### `net.getServingCi` + +```python +net.getServingCi() +``` + +该方法用于获取服务小区ID。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回服务小区ID。失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.getServingCi() +94938399 +``` + + + +### `net.getMnc` + +```python +net.getMnc() +``` + +该方法用于获取附近小区的mnc。该接口获取结果即为`net.getCellInfo()`接口获取结果中的mnc集合。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回一个list类型的数组，包含小区`mnc`，格式为：`[mnc, ……, mnc]`。数组成员数量并非固定不变，位置不同、信号强弱不同等都可能导致获取的结果不一样。 + + 失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.getMnc() +[0, 0] +``` + + + +### `net.getServingMnc` + +```python +net.getServingMnc() +``` + +该方法用于获取服务小区的mnc。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回服务小区`mnc`。失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.getServingMnc() +1 +``` + + + +### `net.getMcc` + +```python +net.getMcc() +``` + +该方法用于获取附近小区的mcc。该接口获取结果即为`net.getCellInfo()`接口获取结果中的mcc集合。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回一个list类型的数组，包含小区`mcc`，格式为：`[mcc, ……, mcc]`。数组成员数量并非固定不变，位置不同、信号强弱不同等都可能导致获取的结果不一样。 + + 失败返回整型值`-1`。 + + + +> 注意：EC100Y/EC600S/EC600N/EC600E/EC800E/EC200A/EC600M/EC800M系列的模组，该值是用十六进制来表示，比如下面示例中的十进制数1120，十六进制即0x460，表示移动设备国家代码460，其他型号模组，该值直接用十进制表示，比如移动设备国家代码460，就是用十进制的460来表示。 + + + +**示例：** + +```python +>>> net.getMcc() +[1120, 0] +``` + + + +### `net.getServingMcc` + +```python +net.getServingMcc() +``` + +该方法用于获取服务小区的mcc。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回服务小区的`mcc`，失败返回整型值`-1`。 + + + +> 注意：EC100Y/EC600S/EC600N系列的模组，该值是用十六进制来表示，比如下面示例中的十进制数1120，十六进制即0x460，表示移动设备国家代码460，其他型号模组，该值直接用十进制表示，比如移动设备国家代码460，就是用十进制的460来表示。 + + + +**示例：** + +```python +>>> net.getServingMcc() +1120 +``` + + + +### `net.getLac` + +```python +net.getLac() +``` + +该方法用于获取附近小区的Lac。该接口获取结果即为`net.getCellInfo()`接口获取结果中的lac集合。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回一个list类型的数组，包含小区lac，格式为：`[lac, ……, lac]`。数组成员数量并非固定不变，位置不同、信号强弱不同等都可能导致获取的结果不一样。 + + 失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.getLac() +[21771, 0] +``` + + + +### `net.getServingLac` + +```python +net.getServingLac() +``` + +该方法用于获取服务小区的Lac。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回服务小区`lac`，失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.getServingLac() +56848 +``` + + + +### `net.getModemFun` + +```python +net.getModemFun() +``` + +该方法用于获取当前工作模式。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回当前模组工作模式，失败返回整型值`-1`： + +* 模组工作模式 +| 模式 | 说明 | +| --- | ---------- | +| 0 | 全功能关闭 | +| 1 | 全功能开启（默认）| +| 4 | 飞行模式 | + +**示例：** + +```python +>>> net.getModemFun() +1 +``` + + + +### `net.setModemFun` + +```python +net.setModemFun(fun, rst) +``` + +该方法用于设置当前模组工作模式。 + +**参数：** + +* `fun` - 模组工作模式，整型值 +| 模式 | 说明 | +| --- | ---------- | +| 0 | 全功能关闭 | +| 1 | 全功能开启（默认）| +| 4 | 飞行模式 | + +* `rst` - 重启标志，整型值，可选参数 +| 值 | 说明 | +| --- | ---------- | +| 0 | 设置完不重启（默认） | +| 1 | 设置完重启 | + +**返回值：** + + 设置成功返回整型值`0`，设置失败返回整型值`-1`。 + +**示例：** + +```python +>>> net.setModemFun(4) +0 +``` + + + +### `net.setBand` + +```python +net.setBand(netRat, gsmBand, bandTuple) +``` +该方法用于设置需要的band，即在模组支持的前提下，锁定用户指定的band。 + +* `band`值对照表 + +| 网络制式 | band值 | +| --------------- | ------------------------------------------------------------ | +| EGPRS(GSM) | EGSM900 - 0x1
DCS1800 - 0x2
GSM850 - 0x4
PCS1900 - 0x8 | +| LTE/eMTC/NB-IoT | BAND1 - 0x1
BAND2 - 0x2
BAND3 - 0x4
BAND4 - 0x8
BAND5 - 0x10
BAND8 - 0x80
BAND12 - 0x800
BAND13 - 0x1000
BAND18 - 0x20000
BAND19 - 0x40000
BAND20 - 0x80000
BAND25 - 0x1000000
BAND26 - 0x2000000
BAND27 - 0x4000000
BAND28 - 0x8000000
BAND31 - 0x40000000
BAND66 - 0x20000000000000000
BAND71 - 0x400000000000000000
BAND72 - 0x800000000000000000
BAND73 - 0x1000000000000000000
BAND85 - 0x1000000000000000000000
| + +* BG95M3模组`band`支持表 + +| 网络制式 | 支持的BAND | +| -------- | ------------------------------------------------------------ | +| eMTC | B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B26/B27/B28/B66/B85 | +| NB-IoT | B1/B2/B3/B4/B5/B8/B12/B13/B18/B19/B20/B25/B28/B66/B71/B85 | +| EGPRS | GSM850/EGSM900/DCS1800/PCS1900 | + +* EG912NENAA模组`band`支持表 + +| 网络制式 | 支持的BAND | +| -------- | ------------------------------------ | +| LTE | B1/B3/B5/B7/B8/B20/B28/B31/B72 | +| EGPRS | EGSM900/DCS1800 | + +**参数：** + +* `netRat` - 网络模式，整型值，表示制定要设置的是哪种网络模式下的`band` +| rat值 | 说明 | +| ----- | ----------------------------------------- | +| 0 | 设置GSM网络的band | +| 1 | 设置LTE网络的band | +| 2 | 设置CATM网络的band | +| 3 | 设置NB网络的band | + +* `gsmBand` - `GSM`网络的`band`值，整型值，参照上述`band`值对照表 + +* `bandtuple` - 设置`GSM`网络之外的其他网络模式的`band`值，是一个包含4个元素的元组，每个成员最大不能超过4字节，具体形式：`(band_hh, band_hl, band_lh, band_ll)`，每个元素说明如下： +`band_hh` - band值的高8字节的高4字节 +`band_hl` - band值的高8字节的低4字节 +`band_lh` - band值的低8字节的高4字节 +`band_ll` - band值的低8字节的低4字节 +如果用户最终要设置的`band`值为`band_value`，那么计算方式如下： +`band_hh = (band_value & 0xFFFFFFFF000000000000000000000000) >> 96` +`band_hl = (band_value & 0x00000000FFFFFFFF0000000000000000) >> 64` +`band_lh = (band_value & 0x0000000000000000FFFFFFFF00000000) >> 32` +`band_ll = (band_value & 0x000000000000000000000000FFFFFFFF)` + +**返回值：** + + 设置成功返回整型`0`，失败返回整型`-1`。 + +>注: +>* 当前可支持模组型号：BG95系列/EG912NENAA +>* BG95不支持设置上述模式1(LTE)下的`band` +>* EG912NENAA仅支持上述模式0(GSM)和模式1(LTE) + +**示例：** + +```python +import net +import utime + +''' +用户可直接使用下面两个接口来设置band和获取band +''' +def set_band(net_rat, band_value): + if net_rat == 0: + retval = net.setBand(0, band_value, (0, 0, 0, 0)) + else: + band_hh = (band_value & 0xFFFFFFFF000000000000000000000000) >> 96 + band_hl = (band_value & 0x00000000FFFFFFFF0000000000000000) >> 64 + band_lh = (band_value & 0x0000000000000000FFFFFFFF00000000) >> 32 + band_ll = (band_value & 0x000000000000000000000000FFFFFFFF) + retval = net.setBand(net_rat, 0, (band_hh, band_hl, band_lh, band_ll)) + return retval + + +def get_band(net_rat): + return net.getBand(net_rat) + +#====================================================================================================== + +''' +设置GSM网络band为0xa，即 DCS1800 + PCS1900 +0xa = 0x2(DCS1800) + 0x8(PCS1900) +''' +def set_gsm_band_example(): + print('Set GSM band to 0xa example:') + gsm_band = get_band(0) + print('GSM band value before setting:{}'.format(gsm_band)) + ret = set_band(0, 0xa) + if ret == 0: + print('Set GSM band successfully.') + else: + print('Set GSM band failed.') + utime.sleep(1) # 设置band需要一定时间，延时一段时间再获取新的结果 + gsm_band = get_band(0) + print('GSM band value after setting:{}'.format(gsm_band)) + return ret + + +''' +设置eMTC网络band为0x15，即设置 BAND1+BAND3+BAND5 +0x15 = 0x1(BAND1) + 0x4(BAND3) + 0x10(BAND5) +''' +def set_camt_band_example(): + print('Set CATM band to 0x15 example:') + catm_band = get_band(2) + print('CATM band value before setting:{}'.format(catm_band)) + ret = set_band(2, 0x15) + if ret == 0: + print('Set CATM band successfully.') + else: + print('Set CATM band failed.') + utime.sleep(1) # 设置band需要一定时间，延时一段时间再获取新的结果 + catm_band = get_band(2) + print('CATM band value after setting:{}'.format(catm_band)) + return ret + + +''' +设置NB-IoT网络band为0x1000800000000000020011，即设置 BAND1+BAND5+BAND18+BAND71+BAND85 +0x1000400000000000020011 = 0x1 + 0x10 + 0x20000 + 0x400000000000000000 + 0x1000000000000000000000 +''' +def set_nb_band_example(): + print('Set NB band to 0x1000400000000000020011 example:') + nb_band = get_band(3) + print('NB band value before setting:{}'.format(nb_band)) + ret = set_band(3, 0x1000400000000000020011) + if ret == 0: + print('Set NB band successfully.') + else: + print('Set NB band failed.') + utime.sleep(1) # 设置band需要一定时间，延时一段时间再获取新的结果 + nb_band = get_band(3) + print('NB band value after setting:{}'.format(nb_band)) + return ret + + +def main(): + set_gsm_band_example() + utime.sleep(1) + set_camt_band_example() + utime.sleep(1) + set_nb_band_example() + + +if __name__ == '__main__': + main() + + +#=================================================================================================== +#运行结果 +Set GSM band to 0xa example: +GSM band value before setting:0xf +Set GSM band successfully. +GSM band value after setting:0xa + +Set CATM band to 0x15 example: +CATM band value before setting:0x10000200000000090e189f +Set CATM band successfully. +CATM band value after setting:0x15 + +Set NB band to 0x1000400000000000020011 example: +NB band value before setting:0x10004200000000090e189f +Set NB band successfully. +NB band value after setting:0x1000400000000000020011 + +``` + + + +### `net.getBand` + +```python +net.getBand(netRat) +``` + +该方法用于获取当前某个网络制式下的band设置值。 + +**参数：** + +* `netRat` - 网络模式，整型值，表示制定要设置的是哪种网络模式下的`band` +| rat值 | 说明 | +| ----- | ----------------------------------------- | +| 0 | 设置GSM网络的band | +| 1 | 设置LTE网络的band | +| 2 | 设置CATM网络的band | +| 3 | 设置NB网络的band | + +**返回值：** + +返回十六进制字符串形式的band值。 + +>注: +>* 当前可支持模组型号：BG95系列/EG912NENAA +>* BG95不支持设置上述模式1(LTE)下的`band` +>* EG912NENAA仅支持上述模式0(GSM)和模式1(LTE) + +**示例：** + +```python +net.getBand(2) +'0x10000200000000090e189f' # 这是字符串，用户如果需要int型，可通过int(data)来自行转换 +``` + + + +### `net.bandRst` + +```python +net.bandRst() +``` + +该方法用于恢复band初始设定值。 + +**参数：** + +* 无 + +**返回值：** + +成功返回整型`0`，失败返回整型`-1`。 + +>当前可支持模组型号：EG912NENAA + +**示例：** + +```python +''' +先设置成其他band，调用该接口，看是否成功恢复成初始值 +EG912NENAA平台初始值：gsm_band:0x3(EGSM900/DCS1800 ) lte_band:0x8000000000480800D5(B1/B3/B5/B7/B8/B20/B28/B31/B72 ) +''' +>>> net.bandRst() +0 +``` \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sim.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sim.md" new file mode 100644 index 00000000..b13331e4 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sim.md" @@ -0,0 +1,603 @@ +# `sim` - SIM卡相关功能 + +提供sim卡相关功能的接口，如查询sim卡状态、iccid、imsi、电话号码等。 + +> 注意：能成功获取IMSI、ICCID、电话号码的前提是SIM卡状态为1，可通过sim.getStatus()查询。 + +## 方法 + +### `sim.genericAccess` + +``` +sim.genericAccess(simId, cmd) +``` + +通用SIM访问接口 ，用于发送csim指令直接和sim卡交互。 + +**参数描述：** + +* `simId` - SIM卡卡槽编号，整型值，0表示SIM0，1表示SIM1，目前仅支持0。 +* `cmd` - 移动终端以GSM 51.011中描述的格式传递给SIM的命令，字符串类型。 + +**返回值描述：** + +成功： 返回元组数据。格式`(len，data)`，其中`len`为整型，表示`data`的长度。`data`为字符串类型，表示返回的数据内容。 + +失败： 返回整型值`-1`。 + +> 注意：仅EC100Y/EC200N/EC600N/EC600S/EC800N/EG912N/EG915N系列支持该方法。 + +**示例：** + +```python +>>> sim.genericAccess(0,'80F2000016') +(48, '623E8202782183027FF08410A0000000871002FF86FF9000') +``` + + + +### `sim.getImsi` + +```python +sim.getImsi() +``` + +该方法用于获取sim卡的IMSI。 + +**参数描述：** + +- 无 + + +**返回值描述：** + +成功： 返回字符串类型，数据值为`IMSI`。 + +失败： 返回整型值`-1`。 + +**示例：** + +```python +>>> import sim +>>> sim.getImsi() +'460105466870381' +``` + + + +### `sim.getIccid` + +```python +sim.getIccid() +``` + +该方法用于获取sim卡的ICCID。 + +**参数描述：** + +- 无 + +**返回值描述：** + +成功： 返回字符串类型，数据值为`ICCID`。 + +失败： 返回整型值`-1`。 + +**示例：** + +```python +>>> sim.getIccid() +'89860390845513443049' +``` + + + +### `sim.getPhoneNumber` + +```python +sim.getPhoneNumber() +``` + +该方法用于获取sim卡的电话号码，需要先进行写入本SIM卡电话卡号码。 + +**参数描述：** + +- 无 + +**返回值描述：** + +成功： 返回字符串数据类型的电话号码。 + +失败： 返回整型值`-1`。 + +>BC25系列不支持此方法 + +**示例：** + +```python +>>> sim.getPhoneNumber() +'+8618166328752' +``` + + + +### `sim.getStatus` + +```python +sim.getStatus() +``` + +该方法用于查询当前SIM卡状态。 + +**参数描述：** + +- 无 + +**返回值描述：** + +sim卡状态码，整型值，具体说明如下： + +| 返回值 | 说明 | +| ------ | ------------------------------------------------------------ | +| 0 | SIM卡不存在/被移除 | +| 1 | SIM已经准备好 | +| 2 | SIM卡已锁定，等待CHV1密码 | +| 3 | SIM卡已被阻拦，需要CHV1密码解锁密码 | +| 4 | 由于SIM/USIM个性化检查失败，SIM卡被锁定 | +| 5 | 由于PCK错误导致SIM卡被阻拦，需要MEP密码解除阻拦 | +| 6 | 需要隐藏电话簿条目的密钥 | +| 7 | 需要解锁隐藏密钥的编码 | +| 8 | SIM卡已锁定，等待CHV2密码 | +| 9 | SIM卡被阻拦，需要CHV2解锁密码 | +| 10 | 由于网络个性化检查失败，SIM卡被锁定 | +| 11 | 由于NCK不正确，SIM卡被阻栏，需要MEP解锁密码 | +| 12 | 由于子网络锁个性化检查失败，SIM卡被锁定 | +| 13 | 由于错误的NSCK，SIM卡被阻拦，需要MEP解锁密码 | +| 14 | 由于服务提供商个性化检查失败，SIM卡被锁定 | +| 15 | 由于SPCK错误，SIM卡被阻拦，需要MEP解锁密码 | +| 16 | 由于企业个性化检查失败，SIM卡被锁定 | +| 17 | 由于CCK不正确，SIM卡被阻止，需要MEP解锁密码 | +| 18 | SIM正在初始化，等待完成 | +| 19 | 使用CHV1/CHV2通用PIN码解锁CHV1码，解锁CHV2码进而来解锁PIN被阻拦 | +| 20 | SIM卡无效 | +| 21 | 未知状态 | + + + +### `sim.enablePin` + +```python +sim.enablePin(pin) +``` + +该方法用于开启PIN码验证。开启后需要输入正确的PIN码进行验证，成功后，sim卡才能正常使用。需要注意最多3次尝试机会，连续3次错误后sim卡被锁定，需要PUK来解锁。 + +**参数描述：** + +- `pin` - PIN码，字符串类型，一般默认是‘1234’，最大长度不超过15字节。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列PIN密码最大支持四位字符串。 + +**示例：** + +```python +>>> sim.enablePin("1234") +0 +``` + + + +### `sim.disablePin` + +```python +sim.disablePin(pin) +``` + +该方法用于取消PIN码验证。 + +**参数描述：** + +- `pin` - PIN码，字符串类型，一般默认是‘1234’，最大长度不超过15字节。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列PIN密码最大支持四位字符串。 + +**示例：** + +```python +>>> sim.disablePin("1234") +0 +``` + + + +### `sim.verifyPin` + +```python +sim.verifyPin(pin) +``` + +PIN码验证：用于SIM卡开启PIN码验证后，如果需要启用SIM卡，可以调用此方法来临时使本次的SIM卡正常使用，下次开机需要重新调用此方法进行验证(或者可以调用取消PIN验证的接口，重新开机后不需要重新PIN验证)。 + +**参数描述：** + +- `pin` - PIN码，字符串类型，一般默认是‘1234’，最大长度不超过15字节。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列PIN密码最大支持四位字符串。 + +**示例：** + +```python +>>> sim.verifyPin("1234") +0 +``` + + + +### `sim.unblockPin` + +```python +sim.unblockPin(puk, newPin) +``` + +该方法用于SIM卡解锁：当多次输入PIN/PIN2码错误需要用PUK码解锁。如果PUK码输入错误10次，SIM卡将永久锁定自动报废。 + +**参数描述：** + +- `puk` - PUK码，字符串类型，长度8位数字，最大长度不超过15字节。 +- `newPin` - 新PIN码，字符串类型，最大长度不超过15字节。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列PIN密码最大支持四位字符串；PUK码最大支持八位字符串。 + +**示例：** + +```python +>>> sim.unblockPin("12345678", "0000") +0 +``` + + + +### `sim.changePin` + +```python +sim.changePin(oldPin, newPin) +``` + +该方法用于更改sim卡PIN码。 + +**参数描述：** + +- `oldPin` - 旧的PIN码，字符串类型，最大长度不超过15字节。 +- `newPin` - 新的PIN码，字符串类型，最大长度不超过15字节。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列PIN密码最大支持四位字符串。 + +**示例：** + +```python +>>> sim.changePin("1234", "4321") +0 +``` + + + +### `sim.readPhonebook` + +```python +sim.readPhonebook(storage, start, end, username) +``` + +读电话簿：用于获取指定存储位置上的电话本中的一条或多条电话号码记录。 + +**参数描述：** + +- `storage` - 需要读取电话号码记录的电话本存储位置，整型值，可选参数值如下： + +| 值 | 含义 | +| ---- | ------------------------------------------------------------ | +| 0 | 拨号列表 | +| 1 | 紧急电话号码 | +| 2 | 固定拨号号码 | +| 3 | 上次拨打电话号码 | +| 4 | 未接来电 | +| 5 | 终端设备电话薄 | +| 6 | 中断设备电话薄和SIM/USIM电话薄 | +| 7 | 本SIM卡电话号码(需要获取正确的电话号码进行写入) | +| 8 | 已接来电 | +| 9 | 本SIM卡电话薄 | +| 10 | 选择应用电话薄(如果USIM的应用已激活将选用ADF SUIM下的DF电话薄) | +| 11 | SIM卡中的MBDN | +| 12 | SIM卡中的MN | +| 13 | 系统拨叫号码，网络服务拨号 | +| 14 | 来电信息 | +| 15 | 呼出信息 | + +- `start` - 需要读取电话号码记录的起始编号，整型值，`start`为 `0` 表示不使用编号获取电话号码记，`start`应小于等于`end`。 +- `end` - 需要读取电话号码记录的结束编号，整型值，必须满足：`end - start <= 20`。 +- `username` - 电话号码中的用户名，字符串类型，当 start为 0 时有效，暂不支持中文，最大长度不超过30字节。
注意：按username进行匹配时，并不是按完整的单词进行匹配，只要电话簿中已有记录的name是以username开头，那么就会匹配上。 + +**返回值描述：** + +成功： 返回元组数据，格式`(record_number, [(index, username, phone_number), ... , (index, username, phone_number)])`，具体如下： + +| 参数 | 类型 | 含义 | +| --------------- | ------ | -------------------- | +| `record_number` | 整型 | 读取的记录数量 | +| `index` | 整型 | 在电话簿中的索引位置 | +| `username` | 字符串 | 电话号码的用户名 | +| `phone_number` | 字符串 | 电话号码 | + +失败：返回整型值`-1`。 + +>BC25系列不支持此方法。 + +**示例：** + +```python +>>> sim.readPhonebook(9, 1, 4, "") +(4,[(1,'Tom','15544272539'),(2,'Pony','15544272539'),(3,'Jay','18144786859'),(4,'Pondy','15544282538')]) +>>> sim.readPhonebook(9, 0, 0, "Tom") +(1, [(1, 'Tom', '18144786859')]) +>>> sim.readPhonebook(9, 0, 0, "Pony") +(1, [(2, 'Pony', '17744444444')]) +>>> sim.readPhonebook(9, 0, 0, "Pon") #注意，这里只要是包含了‘pon’,都会被匹配上 +(2, [(2, 'Pony', '17744444444'),(4,'Pondy','15544282538')]) +``` + + + +### `sim.writePhonebook` + +```python +sim.writePhonebook(storage, index, username, number) +``` + +写电话簿：用于向选定的存储位置，写入一条电话记录。 + +**参数描述：** + +- `storage` - 需要写入电话号码记录的电话本存储位置，整型值，具体可选参数同上`sim.readPhonebook`中的`storage` ： + +- `index` - 需要写入电话号码记录的在电话簿中的编号，整型值，范围`1 ~ 500`。 +- `username` - 电话号码的用户名，字符串类型，长度范围不超过30字节，暂不支持中文名。 +- `number` - 电话号码，字符串类型，最大长度不超过20字节。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列不支持此方法。 + +**示例：** + +```python +>>> sim.writePhonebook(9, 1, 'Tom', '18144786859') +0 +``` + + + +### `sim.setCallback` + +```python +sim.setCallback(usrFun) +``` + +热插拔注册监听回调函数：用于注册监听回调函数。在开启SIM卡热插拔功能的情况下，当SIM卡有插拔动作，将调用此方法注册的回调函数。 + +**参数描述：** + +* `usrFun` - 回调函数名，回调函数格式以及回调函数的参数说明如下： + +```python +def usrFun(args): + pass +``` + +| 参数 | 类型 | 含义 | +| ------ | ---- | --------------------------------------------------------- | +| `args` | 整形 | 当前SIM卡插拔状态：`1` 表示SIM卡插入；`2` 表示 SIM卡拔出 | + +**返回值描述：** + +返回一个整型值，`0`表示注册成功，`-1`表示注册失败。 + +> BC25系列不支持此方法。 + +**示例：** + +```python +import sim + +def usrCallback(args): + simstates = args + print('sim states:{}'.format(simstates)) + +sim.setCallback(usrCallback) +``` + + + +### `sim.setSimDet` + +```python +sim.setSimDet(switch, triggerLevel) +``` + +SIM卡热插拔开关：用于设置SIM卡热插拔相关配置。 + +**参数描述：** + +- `switch` - 开启或者关闭SIM卡热插拔功能，整型值，`0`：关闭 , `1`：打开。 +- `triggerLevel` - 整型值，根据SIM卡实际的在位电平进行设置，如果SIM卡插入时在位电平为高则设置为1，如果为低设置为0。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +> BC25系列不支持此方法。 + +**示例：** + +```python +>>> sim.setSimDet(1, 0) +0 +``` + + + +### `sim.getSimDet` + +```python +sim.getSimDet() +``` + +该方法用于获取SIM卡热插拔相关配置。 + +**参数描述：** + +- 无 + + +**返回值描述：** + +成功： 返回元组数据，格式`(detenable, insertlevel)`，具体说明如下： + +| 参数 | 类型 | 含义 | +| ------------- | ---- | -------------------------------------------- | +| `detenable` | 整型 | 开启或者关闭SIM卡热插拔功能，0：关闭 1：打开 | +| `insertlevel` | 整型 | 高低电平配置(0/1) | + +失败： 返回`-1`。 + +>BC25系列不支持此方法。 + +**示例：** + +```python +>>> sim.getSimDet() +(1, 0) +``` + + + +### `sim.getCurSimid` + +```python +sim.getCurSimid() +``` + +该方法用于获取当前卡的SIM卡卡槽编号(simId)。 + +**参数描述：** + +- 无 + +**返回值描述：** + +成功： 返回当前`simId`(`0`或`1`，分别表示`SIM1`或者`SIM2`)。 + +失败： 返回`-1`。 + +>支持该方法的模组：EC600M/EC800M系列。 + +**示例：** + +```python +>>> sim.getCurSimid() //获取当前卡，当前是卡1 +0 +``` + + + +### `sim.switchCard` + +```python +sim.switchCard(simId) +``` + +该方法用于sim卡切卡。 + +**参数描述：** + +- `simId` - SIM卡卡槽编号，整型值，0表示SIM1，1表示SIM2。 + +**返回值描述：** + +返回一个整型值，`0`表示成功，`-1`表示失败。 + +>支持该方法的模组：EC600M/EC800M系列。 + +**示例：** + +```python +>>> sim.getCurSimid() //获取当前卡，当前是卡1 +0 +>>> sim.switchCard(1) //切到卡2 +0 +>>> sim.getCurSimid() //获取当前卡，成功切到卡2 +1 +``` + + + +### `sim.setSwitchcardCallback` + +```python +sim.setSwitchcardCallback(usrFun) +``` + +该方法用于注册监听SIM卡切卡状态回调函数：注册监听回调函数,响应SIM卡切卡动作。 + +**参数描述：** + +* `usrFun` - 回调函数名，回调函数格式以及回调函数的参数说明如下： + +```python +def usrFun(args): + pass +``` + +| 参数 | 类型 | 含义 | +| ---- | ---- | ----------------------------------------------------------- | +| args | 整形 | 切换SIM卡结果：`7` -表示切换SIM成功，`8`- 表示切换SIM卡失败 | + +**返回值描述：** + +返回一个整型值，`0`表示注册成功，`-1`表示注册失败。 + +> 支持该方法的模组：EC600M/EC800M系列。 +> +> 注意以下几点：
1、目标卡不存在或者目标卡状态异常；
2、目标卡是当前卡；
以上情况切卡方法`sim.switchCard`直接返回-1，不触发此接口设置的回调函数。 + +**示例：** + +```python +import sim + +def usrCallback(args): + switchcard_state = args + print('sim switchcard states:{}'.format(switchcard_state)) + +sim.setSwitchcardCallback(usrCallback) +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sms.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sms.md" new file mode 100644 index 00000000..d3070ac6 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/sms.md" @@ -0,0 +1,452 @@ +# `sms` - 短信功能 + +模块功能：该模块提供短信功能相关方法，包括读取、发送、删除短信等方法。 + +> 注意：BC25/EC600M系列不支持此功能。 + + + +## 方法 + +### `sms.sendTextMsg` + +``` +sms.sendTextMsg(phoneNumber, msg, codeMode) +``` + +该方法用于发送TEXT类型的消息（不支持发送空短信）。 + +**参数描述：** + +* `phoneNumber` - 接收方手机号码，字符串类型，最大长度不超过20字节。 +* `msg` - 待发送消息，字符串类型，长度不超过140个字节。 +* `codeMode` -使用的字符编码方式，字符串类型，取值范围如下： + +| 值 | 含义 | +| -------- | ---------------------------------------------- | +| `'GSM'` | GSM编码方式，用于发送英文短信 | +| `'UCS2'` | UCS2编码方式，可以用于发送中文短信以及英文短信 | + +**返回值描述：** + +返回一个整型值，`0`表示发送成功，`-1`表示发送失败。 + +**示例：** + +```python +# -*- coding: UTF-8 -*- +import sms + +sms.sendTextMsg('18158626517', '这是一条中文测试短信！', 'UCS2') +sms.sendTextMsg('18158626517', 'Hello, world.', 'GSM') +sms.sendTextMsg('18158626517', '这是一条夹杂中文与英文的测试短信,hello world!', 'UCS2') +``` + + + +### `sms.sendPduMsg` + +``` +sms.sendPduMsg(phoneNumber, msg, codeMode) +``` + +该方法用于发送PDU类型的消息（不支持发送空短信）。 + +**参数描述：** + +* `phoneNumber` - 接收方手机号码，字符串类型，最大长度不超过20字节。 +* `msg` - 待发送消息，字符串类型，长度不超过140个字节。 +* `codeMode` -使用的字符编码方式，字符串类型，取值范围如下： + +| 值 | 含义 | +| -------- | ---------------------------------------------- | +| `'GSM'` | GSM编码方式，用于发送英文短信 | +| `'UCS2'` | UCS2编码方式，可以用于发送中文短信以及英文短信 | + +**返回值描述：** + +返回一个整型值，`0`表示发送成功，`-1`表示发送失败。 + +**示例：** + +```python +# -*- coding: UTF-8 -*- +import sms + +sms.sendPduMsg('18158626517', 'send pdu msg by GSM mode.', 'GSM') +sms.sendPduMsg('18158626517', 'send pdu msg by UCS2 mode.', 'UCS2') +sms.sendPduMsg('18158626517', '这是一条中文测试短信！通过PDU-UCS2模式', 'UCS2') +``` + + + +### `sms.deleteMsg` + +``` +sms.deleteMsg(index) +``` + +该方法用于删除指定索引的消息。 + +**参数描述：** + +* `index` - 索引号，整型值，需要删除短信的索引号。 + +**返回值描述：** + +返回一个整型值，`0`表示删除成功，`-1`表示删除失败。 + +**示例：** + +```python +>>> import sms +>>> sms.deleteMsg(0) +0 +``` + + + +### `sms.setSaveLoc` + +``` +sms.setSaveLoc(mem1, mem2, mem3) +``` + +该方法用于设置短信的存储位置。 + +**参数描述：** + +* `mem1` - 读取和删除消息所在的位置，字符串类型，支持如下参数: + + | 值 | 含义 | + | ------ | --------------------- | + | `"SM"` | SIM消息存储
| + | `"ME"` | 移动设备信息存储
| + | `"MT"` | 暂不支持 | + +* `mem2` - 写入和发送消息所在的位置，字符串类型，支持参数同上`mem1`的值。 + +* `mem3` - 接收消息的存储位置，字符串类型，支持参数同上`mem1`的值。 + +**返回值描述：** + +返回一个整型值，`0`表示设置成功，`-1`表示设置失败。 + +> EC100Y/EC200N/EC600N/EC600S/EC800N/EG912N/EG915N/EC800M/EG810M/EC200A系列如果要改变接收消息的存储位置，需要同时设定mem2 & mem3；EC200U/EC600U/EG912U/EG915U/EC600G/EC800G系列只需设定mem3即可 + +**示例：** + +```python +>>> import sms +>>> sms.setSaveLoc('SM', 'SM', 'SM') +0 +``` + + + +### `sms.getSaveLoc` + +``` +sms.getSaveLoc() +``` + +该方法用于获取当前模块短信存储位置相关信息。 + +**参数描述：** + +* 无 + +**返回值描述：** + +成功： 返回元组数据,格式`([loc1, current_nums, max_nums],[loc2, current_nums, max_nums],[loc3, current_nums, max_nums])`,如下表： + +| 参数 | 类型 | 含义 | +| -------------- | ------ | ------------------------------------------------------------ | +| `loc1` | 字符串 | 读取和删除消息所在的位置，具体含义同`sms.setSaveLoc`中`mem1`的值 | +| `loc2` | 字符串 | 写入和发送消息所在的位置，具体含义同`sms.setSaveLoc`中`mem1`的值 | +| `loc3` | 字符串 | 接收消息的存储位置，具体含义同`sms.setSaveLoc`中`mem1`的值 | +| `current_nums` | 整型 | 当前空间已有短信数量 | +| `max_nums` | 整型 | 当前空间最大短信存储数量 | + +失败：返回`-1`。 + +**示例：** + +```python +>>> sms.getSaveLoc() +(['SM', 2, 50], ['SM', 2, 50], ['SM', 2, 50]) +>>> sms.setSaveLoc('SM','ME','MT') +0 +>>> sms.getSaveLoc() +(['SM', 2, 50], ['ME', 14, 180], ['MT', 2, 50]) +``` + + + +### `sms.getMsgNums` + +``` +sms.getMsgNums() +``` + +该方法用于获取短信的数量。 + +**参数描述：** + +* 无 + +**返回值描述：** + +成功： 返回短信数量值。失败： 返回`-1`。 + +**示例：** + +```python +>>> import sms +>>> sms.getMsgNums() # 执行本行前，先发送一条短信到模块 +1 +``` + + + +### `sms.searchPduMsg` + +``` +sms.searchPduMsg(index) +``` + +该方法用于以PDU方式获取短信内容。 + +**参数描述：** + +* `index` - 需要获取短信的索引，整型值，范围`0 ~ MAX-1`，`MAX`为模块存储短信的最大数量。 + +**返回值描述：** + +成功： 返回字符串类型的PDU数据，为短信内容，包含收到短信的时间，所以相同短信内容的PDU数据是不同的。 + +失败： 返回整型`-1`。 + +**示例：** + +```python +>>> import sms +>>> sms.sendPduMsg('+8618226172342', '123456789aa', 'GSM') # 自己给自己发送一条短信 +>>> sms.searchPduMsg(0) # 以PDU方式获取短信内容，下面PDU格式短信需要解码后才能正常显示短信内容 +'0891683110305005F0240BA19169256015F70000022141013044230B31D98C56B3DD70B97018' +``` + + + +### `sms.searchTextMsg` + +``` +sms.searchTextMsg(index) +``` + +该方法用于以TEXT方式获取短信内容。 + +**参数描述：** + +* `index` - 需要获取短信的索引，整型值，范围`0 ~ MAX-1`，`MAX`为模块存储短信的最大数量。 + +**返回值描述：** + +成功： 返回元组数据，格式`(phoneNumber， msg， msgLen)`，具体参数如下： + +| 参数 | 类型 | 含义 | +| ------------- | ------ | -------------- | +| `phoneNumber` | 字符串 | 短信来源手机号 | +| `msg` | 字符串 | 短信内容 | +| `msgLen` | 整型 | 短信消息长度 | + +失败： 返回整型值`-1`。 + +**示例：** + +```python +>>> import sms +>>> sms.sendPduMsg('+8618226172342', '123456789aa', 'GSM') # 自己给自己发送一条短信 +>>> sms.searchTextMsg(0) # 以TEXT方式获取短信内容 +('+8618226172342', '123456789aa', 22) +``` + + + +### `sms.getPduLength` + +```python +sms.getPduLength(pduMsg) +``` + +该方法用于获取指定PDU短信的长度。 + +**参数描述：** + +- `pduMsg` - PDU短信，字符串类型。 + +**返回值描述：** + +成功： 返回PDU短信长度，整型值。 + +失败： 返回`-1`。 + +**示例：** + +```python +>>> import sms +>>> sms.searchPduMsg(0) +'0891683108501505F0040D91688122162743F200000211529003332318C16030180C0683C16030180C0683E170381C0E87' +>>> sms.getPduLength(sms.searchPduMsg(0)) #注意，是获取PDU短信长度，不是上面字符串的长度 +40 +``` + + + +### `sms.decodePdu` + +```python +sms.decodePdu(pduMsg, pduLen) +``` + +该方法用于PDU解码，解析`sms.searchPduMsg()`接口读取到的PDU数据。 + +**参数描述：** + +- `pduMsg` - PDU短信，字符串类型。 + +- `pduLen` - PDU短信长度，整型值。 + +**返回值描述：** + +成功： 返回元组数据，格式`(phoneNumber， msg， time， msgLen)`，具体参数如下: + +| 参数 | 类型 | 含义 | +| ------------- | ------ | -------------- | +| `phoneNumber` | 字符串 | 短信来源手机号 | +| `msg` | 字符串 | 短信内容 | +| `time` | 整型 | 收到短信的时间 | +| `msgLen` | 整型 | 短信消息长度 | + +失败： 返回整型值`-1`。 + +**示例：** + +```python +>>> import sms +>>>sms.decodePdu('0891683110305005F00405A10110F000081270319043442354516C76CA77ED4FE1FF1A00320030003200315E7496328303975E6CD596C68D445BA34F2067086D3B52A863D09192FF1A4E3B52A88FDC79BB975E6CD596C68D44FF0C5171540C5B8862A47F8E597D751F6D3B3002',20) +>>>('10010', '公益短信：2021年防范非法集资宣传月活动提醒：主动远离非法集资，共同守护美好生活。', '2021-07-13 09:34:44', 118) +``` + + + +### `sms.getCenterAddr` + +```python +sms.getCenterAddr() +``` + +该方法用于获取短信中心号码。 + +**参数描述：** + +- 无 + + +**返回值描述：** + +成功： 返回字符串类型的短信中心号码。 + +失败： 返回整型值`-1`。 + +**示例：** + +```python +>>> import sms +>>> sms.getCenterAddr() +'+8613800551500' +``` + + + +### `sms.setCenterAddr` + +```python +sms.setCenterAddr(addr) +``` + +该方法用于设置短信中心号码。若无特殊需求，不建议更改短信中心号码。 + +**参数描述：** + +- `addr` - 需要设置的短信中心号码，字符串类型。 + + +**返回值描述：** + +返回一个整型值，`0`表示设置成功，`-1`表示设置失败。 + + + +### `sms.setCallback` + +```python +sms.setCallback(usrFun) +``` + +该方法用于注册监听回调函数，当接收到短信时，调用此方法注册的回调函数。 + +**参数描述：** + +* `usrFun` - 回调函数名，回调函数格式以及回调函数的参数说明如下： + +```python +def usrFun(args): + pass +``` + +| 参数 | 类型 | 参数说明 | +| --------- | ------ | -------------------- | +| `args[0]` | 整形 | 当前SIM卡卡槽的simId | +| `args[1]` | 整型 | 短信索引 | +| `args[2]` | 字符串 | 短信存储位置 | + +**返回值描述：** + +返回一个整型值，`0`表示设置成功，`-1`表示设置失败。 + +**示例：** + +```python +# 示例一 +import sms + +def cb(args): + index = args[1] + storage = args[2] + print('New message! storage:{},index:{}'.format(storage, index)) + +sms.setCallback(cb) + +# 示例二 +#短信回调函数新老架构的使用方法不同，如下所示，新架构参照示例一，QPY_V0004_EC600N_CNLC_FW_VOLTE(2021-09-09发布)之前发布的版本参照示例二。 +import sms + +def cb(args): + ind_flag = args[0] + if ind_flag == 4097: + mes_buf, mes_len = args[1], args[2] + print('New message! ind_flag:{},mes_buf:{},mes_len:{}'.format(ind_flag, mes_buf, mes_len)) + elif ind_flag == 4099: + mes_type, storage, index = args[1], args[2], args[3] + print('New message! ind_flag:{},mes_type:{},storage:{},index:{}'.format(ind_flag, mes_type, storage, index)) + elif ind_flag == 4100: + mes_buf = args[1] + print('New message! ind_flag:{},mes_buf:{}'.format(ind_flag, mes_buf)) + elif ind_flag == 4101: + storage,index = args[1], args[2] + print('New message! ind_flag:{},storage:{},index:{}'.format(ind_flag, storage, index)) + +sms.setCallback(cb) +``` + diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/voiceCall.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/voiceCall.md" new file mode 100644 index 00000000..48e49e64 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/voiceCall.md" @@ -0,0 +1,684 @@ +# `voiceCall` - 电话功能 + +`voiceCall`模块提供电话功能相关接口。 + +>注： +>* 支持voiceCall功能的模组： +> EC100Y系列：EC100YCN_AA +> EC200N系列：EC200NCN_AA/EC200NCN_AC/EC200NCN_LA +> EC600N系列：EC600NCN_AA/EC600NCN_LC/EC600NCN_LD/EC600NCN_LF +> EC600S系列：EC600SCN_LA +> EG912N系列：EG912NEN_AA +> EG915N系列：EG915NEU_AG +> EC200A系列：EC200AAU_HA/EC200ACN_DA/EC200ACN_HA/EC200ACN_LA/EC200AEU_HA +> EC200U系列：EC200UAU_AB/EC200UCN_AA/EC200UEU_AA/EC200UEU_AB +> EC600U系列：EC600CEU_AB/EG912UGL_AA/EG915UEU_AB +> BC25系列/EC600G系列/EC800G系列/BG95系列/BG77系列模组不支持voiceCall功能 +>* 其他系列模组需要定制版本才能支持voiceCall功能 + +## 方法 + +### `voiceCall.setAutoAnswer` + +```python +voiceCall.setAutoAnswer(seconds) +``` + +该方法用于设置自动应答时间。 + +**参数：** + +* `seconds` - 自动应答时间，整型值，单位/s，范围：0-255。 + +**返回值：** + + 成功返回整型`0`，失败返回整型`-1`。 + +**示例：** + +```python +>>> import voiceCall +>>> voiceCall.setAutoAnswer(5) +0 +``` + + + +### `voiceCall.callStart` + +```python +voiceCall.callStart(phonenum) +``` + +该方法用于主动拨打电话。 + +**参数：** + +* `phonenum` - 接收方电话号码，字符串类型。 + +**返回值：** + + 成功返回整型`0`，失败返回整型`-1`。 + +**示例：** + +```python +>>> voiceCall.callStart("13855169092") +0 +``` + + + +### `voiceCall.callAnswer` + +```python +voiceCall.callAnswer() +``` + +该方法用于接听电话。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回整型`0`，失败返回整型`-1`。 + +**示例：** + +```python +>>> voiceCall.callAnswer() +0 +``` + + + +### `voiceCall.callEnd` + +```python +voiceCall.callEnd() +``` + +该方法用于挂断电话。 + +**参数：** + +* 无 + +**返回值：** + + 成功返回整型`0`，失败返回整型`-1`。 + +**示例：** + +```python +>>> voiceCall.callEnd() +0 +``` + + + +### `voiceCall.setCallback` + +```python +voiceCall.setCallback(voicecallFun) +``` + +该方法用于注册回调函数。监听不同的通话状态并通过回调反馈给用户。 + +**参数：** + +* `voicecallFun` - 回调函数名，回调函数格式以及回调函数的参数说明如下： +```python +def voicecallFun(args): + pass +``` +`args[0]` - 通话状态，整型值
1：voicecall初始化成功（底层完成，无需用户干预）
2：来电通知，响铃
3：通话接通
4：通话挂断
5：未知错误
6：呼叫等待
7：呼出中
8：呼出失败
9：等待
10：来电通知，响铃（volte通话）
11：通话接通（volte通话）
12：通话挂断（volte通话）
13：呼叫等待（volte通话）
14：呼出中（volte通话）
15：呼出中，对方未响铃（volte通话）
16：等待（volte通话） | + +| 通话状态 | 参数个数 | 参数说明 | +| -------- | ------- | ------------------------------------------------------------ | +| 2/3/9 | 3 | args[0]：通话状态
args[1]：呼叫识别号码
args[2]：电话号码 | +| 4 | 3 | args[0]：通话状态
args[1]：呼叫识别号码
args[2]：通话挂断原因 | +| 6 | 5 | args[0]：通话状态
args[1]：呼叫识别号码
args[2]：电话号码
args[3]：号码类型[129/145],129:非国际号码,145:国际号码
args[4]：CLI状态 | +| 7 | 1 | args[0]：通话状态 | +| 8 | 4 | args[0]：通话状态
args[1]：呼叫识别号码
args[2]：呼叫失败原因
args[3]：指示是否可以从网络端获得in-band tones | +|10/11/12/13/14/15/16| 8 | args[0]：通话状态
args[1]：呼叫识别号码
args[2]：呼叫方向(MO/MT)
args[3]：通话状态
args[4]：业务类型(这里一般都是0，表示voice call，语音通话业务)
args[5]：多方通话标志，0：非多方通话 1：多方通话
args[6]：电话号码
args[7]：号码类型[129/145],129:非国际号码,145:国际号码 | + +**返回值：** + +注册成功返回整型`0`，失败返回整型`-1`。 + +**示例：** + +```python +def voice_callback(args): + if args[0] == 10: + print('voicecall incoming call, PhoneNO: ', args[6]) + elif args[0] == 11: + print('voicecall connected, PhoneNO: ', args[6]) + elif args[0] == 12: + print('voicecall disconnect') + elif args[0] == 13: + print('voicecall is waiting, PhoneNO: ', args[6]) + elif args[0] == 14: + print('voicecall dialing, PhoneNO: ', args[6]) + elif args[0] == 15: + print('voicecall alerting, PhoneNO: ', args[6]) + elif args[0] == 16: + print('voicecall holding, PhoneNO: ', args[6]) + +>>> voiceCall.setCallback(voice_callback) +0 +>>> voiceCall.callStart('10086') +0 +``` + +>注意: +>* 1、以上仅适用2021-09-09之后发布的支持语音通话的版本 +>* 2、QPY_V0004_EC600N_CNLC_FW_VOLTE(2021-09-09发布)之前发布的版本都按照以下规则使用voiceCall + +`args[0]` - 通话状态，整型值
4103：来电通知，响铃（volte通话）
4104：通话接通（volte通话）
4105：通话挂断（volte通话）
4106：呼叫等待（volte通话） + +其余参数说明定义未变 + +**示例：** + +```python +def voice_callback(args): + if args[0] == 4106: + print('voicecall is waiting') + elif args[0] == 4105: + print('voicecall disconnect') + elif args[0] == 4104: + print('voicecall connected, CallNO: ', args[6]) + elif args[0] == 4103: + print('voicecall incoming call, PhoneNO: ', args[6]) +``` + + + +### `voiceCall.setAutoCancel` + +```python +voiceCall.setAutoCancel(enable) +``` + +该方法用于使能来电自动挂断功能。 + +**参数：** + +* `enable` - 开启或者关闭来电自动挂断功能，`1`：开启，`0`：关闭 (默认不开启) + +**返回值：** + + 成功返回整型`0`，失败返回整型`-1`。 + +>注：EC200AAU_HA/EC200ACN_DA/EC200ACN_HA/EC200ACN_LA/EC200AEU_HA系列模组支持该方法 + +**示例：** + +```python +#手机呼叫模块，默认不会自动挂断 +>>> voiceCall.getAutoCancelStatus() +0 + +#设置自动挂断功能，手机呼叫模块，默认自动挂断 +>>> voiceCall.setAutoCancel(1) +0 +>>> voiceCall.getAutoCancelStatus() +1 +``` + + + +### `voiceCall.getAutoCancelStatus` + +```python +voiceCall.getAutoCancelStatus() +``` + +该方法用于获取来电自动挂断使能状态。 + +**参数：** + +* 无 + +**返回值：** + +`0`:来电自动挂断使能关闭，来电不会被模组自动挂断 + +`1`:来电自动挂断使能开启，来电会被模组自动挂断 + +>注：EC200AAU_HA/EC200ACN_DA/EC200ACN_HA/EC200ACN_LA/EC200AEU_HA系列模组支持该方法 + +**示例：** + +```python +#手机呼叫模块，默认不会自动挂断 +>>> voiceCall.getAutoCancelStatus() +0 + +#设置自动挂断功能，手机呼叫模块，默认自动挂断 +>>> voiceCall.setAutoCancel(1) +0 +>>> voiceCall.getAutoCancelStatus() +1 +``` + + + +### `voiceCall.startDtmf` + +```python +voiceCall.startDtmf(dtmf, duration) +``` + +该方法用于设置DTMF音。 + +**参数：** + +* `dtmf` - DTMF字符串，字符串类型，最大字符数：32个，有效字符数有：`0-9、A、B、C、D、*、#` +* `duration` - 持续时间，整型值，范围：100-1000，单位：毫秒 + +**返回值：** + + 设置成功返回整型`0`，设置失败返回整型`-1`。 + +>注：该方法仅在语音通话过程中使用生效 + +**示例：** + +```python +>>> voiceCall.startDtmf('A',100) +0 +``` + + + +### `voiceCall.dtmfDetEnable` + +```python +voiceCall.dtmfDetEnable(enable) +``` + +该方法用于使能DTMF识别功能，默认不开启DTMF识别 + +**参数：** + +* `enable` - 使能开关，整型值，取值`0/1`，`0`：不开启DTMF识别，`1`：开启DTMF识别 + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`。 + +>注支持voiceCall功能的模组型号中，EC600N/EC600S/EC800N/EG912N/EG915N系列支持该方法 +> + +**示例：** + +``` +参考voiceCall.dtmfSetCb方法示例 +``` + + + +### `voiceCall.dtmfSetCb` + +```python +voiceCall.dtmfSetCb(dtmfFun) +``` + +该方法用于注册DTMF识别功能的回调接口。 + +**参数：** + +* `dtmfFun` - 回调函数名，回调函数格式以及回调函数的参数说明如下： + +```Python +def dtmfFun(args): + pass +``` + +| 参数 | 类型 | 含义 | +| ------- | ---- | ------------------------------------------ | +| args | 字符串 | 对端输入的DTMF字符 | + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`。 + +>注：支持voiceCall功能的模组型号中，EC600N/EC600S/EC800N/EG912N/EG915N系列支持该方法 +> + +**示例：** + +```python +>>> def cb(args): +... print(args) +... + +>>> voiceCall.dtmfSetCb(cb) +0 +>>> voiceCall.dtmfDetEnable(1) +0 + +>>> voiceCall.callStart('13855169092') +0 +>>> +1 #手机端按下1，callback中会收到按下的字符“1” + +8 #手机端按下8 + +9 #手机端按下9 +``` + + + +### `voiceCall.setFw` + +```python +voiceCall.setFw(reason, fwmode, phonenum) +``` + +该方法用于控制呼叫转移补充业务。 + +**参数：** + +* `reason` - 呼叫转移的条件，整型值，具体如下说明： + +| `reason`值 | 参数说明 | +| ------- | ------------- | +| 0 | 无条件的 | +| 1 | 用户忙 | +| 2 | 用户无响应 | +| 3 | 用户不可达 | + +* `fwMode` - 对呼叫转移的控制，整型值，具体如下说明： + +| `fwMode`值 | 参数说明 | +| ------- | ------------- | +| 0 | 禁用 | +| 1 | 启用 | +| 2 | 查询状态 | +| 3 | 注册 | +| 4 | 擦除 | + +* `phonenum` - 呼叫转移的目标电话，字符串类型 + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`。 + + + +### `voiceCall.setChannel` + +```python +voiceCall.setChannel(device) +``` + +该方法用于设置通话时的声音输出通道，默认是通道0，即听筒。 + +**参数：** + +* `device` - 输出通道，整型值，具体如下说明： + +| `device`值 | 参数说明 | +| ------- | ------------- | +| 0 | 听筒 | +| 1 | 耳机 | +| 2 | 喇叭 | + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`。 + +**示例：** + +```python +>>> voiceCall.setChannel(2) #切换到喇叭通道 +0 +``` + + + +### `voiceCall.getVolume` + +```python +voiceCall.getVolume() +``` + +该方法用于获取电话当前音量大小。 + +**参数：** + +* 无 + +**返回值：** + +返回整型音量值。 + + + +### `voiceCall.setVolume` + +```python +voiceCall.setVolume(volume) +``` + +该方法用于设置电话音量大小。 + +**参数:** + +* `volume` - 音量等级，整型值，范围`（0 ~ 11）`，数值越大，音量越大 + +**返回值：** + +设置成功返回整型`0`，失败返回整型`-1`。 + + + + +### `voiceCall.setAutoRecord` + +```python +voiceCall.setAutoRecord(enable, recordType, recordMode, filename) +``` + +该接口用于使能自动录音功能。默认关闭自动录音，自动录音使能需要在通话前设置完毕。 + +**参数：** + +* `enable` - 使能开关，整型值，取值`【0/1】`，`0`：关闭自动录音功能 ，`1`：开启自动录音功能 +* `recordType` - 录音文件类型，整型值，具体如下： +| `recordType`值 | 说明 | +| -------------- | ---- | +| 0 | AMR | +| 1 | WAV | + +* `recordMode` - 模式，整型值，具体如下： +|`recordMode`值|说明 | +|----------|--------| +| 0 | RX | +| 1 | TX | +| 2 | MIX | + +* `filename` - 期望存储的文件名，字符串类型，需包含完整路径。 + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`， 不支持该接口返回字符串`"NOT SUPPORT"`。 + +**示例：** + +```python +>>> voiceCall.setAutoRecord(1,0,2,'U:/test.amr') +0 +``` + + + +### `voiceCall.startRecord` + +```python +voiceCall.startRecord(recordType, recordMode, filename) +``` + +该方法用于开始通话录音。 + +**参数：** + +* `recordType` - 录音文件类型，整型值，具体如下： +| `recordType`值 | 说明 | +| -------------- | ---- | +| 0 | AMR | +| 1 | WAV | + +* `recordMode` - 模式，整型值，具体如下： +|`recordMode`值|说明 | +|----------|--------| +| 0 | RX | +| 1 | TX | +| 2 | MIX | + +* `filename` - 期望存储的文件名，字符串类型，需包含完整路径。 + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`，不支持该接口返回字符串`"NOT SUPPORT"`。 + +**示例：** + +```python +>>> voiceCall.startRecord(0,2,'U:/test.amr') +0 +``` + + + +### `voiceCall.stopRecord` + +```python +voiceCall.stopRecord() +``` + +该方法用于停止通话录音。 + +**参数：** + +* 无 + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`， 不支持该接口返回字符串`"NOT SUPPORT"`。 + +**示例：** + +```python +>>> voiceCall.stopRecord() +0 +``` + + + +### `voiceCall.readRecordStream` + +```python +voiceCall.readRecordStream(readBuf, bufLen) +``` + +该方法用于读取录音流数据。 + +**参数：** + +* `readBuf` - 【out】存储读取到的数据 + +* `bufLen` - 【in】期望读取的字符串长度，（不能超过readBuf申请的字节长度） + +**返回值：** + +读取成功返回读取到的数据长度，读取失败返回整型`-1`，不支持该接口返回字符串`"NOT SUPPORT"`。 + +>说明： +>* 录音流第一包数据均是对应格式文件的文件头 +>* wav格式录音流第一包数据不包含文件大小，需结束录音后自行计算 + +**示例：** + +同`voiceCall.startRecordStream`方法示例 + + + +### `voiceCall.startRecordStream` + +```python +voiceCall.startRecordStream(recordType, recordMode, callbackFun) +``` + +该方法用于开始通话录音（流形式）。 + +**参数：** + +* `recordType` - 录音文件类型，整型值，具体如下： +| `recordType`值 | 说明 | +| -------------- | ---- | +| 0 | AMR | +| 1 | WAV | + +* `recordMode` - 模式，整型值，具体如下： +|`recordMode`值|说明 | +|----------|--------| +| 0 | RX | +| 1 | TX | +| 2 | MIX | + +* `callbackFun` - 回调函数名，回调函数格式以及回调函数的参数说明如下： +```python +def recordStreamCallback(args): + pass +``` +| 参数 | 类型 | 含义 | +| ------- | ---- | -------------------- | +| args[0] | 字符串 | 录音流数据 | +| args[1] | 整型 | 录音流数据长度 | +| args[2] | 整型 | 录音状态
-1：录音出错
0：开始录音
1：返回录音数据
2：录音暂停
3：录音结束
4：空间满 | + +**返回值：** + +设置成功返回整型`0`，设置失败返回整型`-1`，不支持该接口返回字符串`"NOT SUPPORT"`。 + +>说明： +>* 录音流第一包数据均是对应格式文件的文件头 +>* wav格式录音流第一包数据不包含文件大小，需结束录音后自行计算 + +**示例：** + +```python +>>> import voiceCall +>>> import audio + +>>> f=open('usr/mia.amr','w') + +>>> def cb(para): +... if(para[2] == 1): +... read_buf = bytearray(para[1]) +... voiceCall.readRecordStream(read_buf,para[1]) +... f.write(read_buf,para[1]) +... del read_buf +... elif(para[2] == 3): +... f.close() +... +>>> voiceCall.callStart('13855169092') +0 +>>> voiceCall.startRecordStream(0,2,cb) +0 +//此处挂断电话(MO/MT侧挂断都可以) +>>> uos.listdir('usr') +['system_config.json', 'mia.amr'] +>>> aud=audio.Audio(0) +>>> aud.setVolume(11) +0 +>>> aud.play(2,1,'U:/mia.amr') +0 +``` \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/wifilocator.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/wifilocator.md" index e69de29b..1e467d3d 100644 --- "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/wifilocator.md" +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/wifilocator.md" @@ -0,0 +1,68 @@ +# `class wifilocator` - WIFI定位 + +`wifilocator`对象提供WIFI定位功能，获取模组经纬度坐标信息。 + +> 注意：当前仅EC600S/EC600N/EC800N/EC200U/EC600U系列支持该功能。 + +**示例：** + +```python +import wifilocator +# 创建wifilocato对象 +wifiloc = wifilocator.wifilocator("xxxxxxxxxxxxxxxx") +# 获取模块坐标信息 +wifiloc.getwifilocator() +# 返回结果 (117.1152877807617, 31.82142066955567, 100) +# 上面使用的密钥"xxxxxxxxxxxxxxxx"指代token，具体需要向移远申请 +``` + +## 构造函数 + +### `wifilocator.wifilocator` + +```python +class wifilocator.wifilocator(token) +``` + +创建wifilocator对象，配置wifi定位套件token信息。 + +**参数描述：** + +- `token` - 密钥，字符串类型，16位字符组成，需要申请。 + + + +## 方法 + +### wifilocator.getwifilocator + +```python +wifilocator.getwifilocator() +``` + +该方法用于获取模组经纬度坐标信息。 + +**参数描述** + +无 + +**返回值描述：** + +成功返回模组经纬度坐标信息，元组格式：`(longtitude, latitude, accuracy)`； + +`longtitude` ： 经度 + +`latitude` ：纬度 + +`accuracy` ：精确度，单位米 + +失败返回错误码说明如下： + +`1` – 当前网络异常，请确认拨号是否正常 + +`2` – 密钥长度错误，必须为16字节 + +`3` – 获取坐标出错 + + + -- Gitee