diff --git a/rt-thread-version/rt-thread-standard/programming-manual/at/at.md b/rt-thread-version/rt-thread-standard/programming-manual/at/at.md index a35117172f758c3197709d85844fae5bc5ccb562..f0224959e1fced9c99340b29b8a24386538f5281 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/at/at.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/at/at.md @@ -92,21 +92,21 @@ AT 组件是基于 RT-Thread 系统的 `AT Server` 和 `AT Client` 的实现， 上面配置选项可以直接在 `rtconfig.h` 文件中添加使用，也可以通过组件包管理工具 Env 配置选项加入，ENV 中具体路径如下： ```c -RT-Thread Components ---> - Network ---> - AT commands ---> - [*] Enable AT commands - [*] Enable debug log output - [*] Enable AT commands server - (uart3) Server device name - (256) The maximum length of server data accepted - The commands new line sign (\r\n) ---> - [ ] Enable AT commands client - [*] Enable command-line interface for AT commands - [ ] Enable print RAW format AT command communication data -``` - -添加配置完成之后可以使用命令行重新生成工程，或使用 scons 来进行编译生成。 + -> RT-Thread Components + -> Network + --- Enable AT commands + [*] Enable debug log output + [*] Enable AT commands server + (uart3) Server device name + (256) The maximum length of server data accepted + The commands new line sign (\r\n) ---> + [ ] Enable AT commands client + [*] Enable CLI(Command-Line Interface) for AT commands + [ ] Enable print RAW format AT command communication data + (128) The maximum length of AT Commands buffer +``` + +添加配置完成之后可以使用命令行重新生成工程，或使用 scons 来进行编译。 ### AT Server 初始化 ### @@ -354,17 +354,18 @@ AT Server 默认已支持多种基础命令（ATE、ATZ 等），其中部分命 上面配置选项可以直接在 `rtconfig.h` 文件中添加使用，也可以通过组件包管理工具 Env 配置选项加入，ENV 中具体路径如下： ```c -RT-Thread Components ---> - Network ---> - AT commands ---> - [*] Enable AT commands - [ ] Enable debug log output - [ ] Enable AT commands server - [*] Enable AT commands client - (1) The maximum number of supported clients - [*] Enable BSD Socket API support by AT commnads - [*] Enable command-line interface for AT commands - [ ] Enable print RAW format AT command communication data + -> RT-Thread Components + -> Network + --- Enable AT commands + [ ] Enable debug log output + [ ] Enable AT commands server + [*] Enable AT commands client + (1) The maximum number of supported clients + [*] Enable BSD Socket API support by AT commnads + [ ] Enable BSD Socket API support about AT server + [*] Enable CLI(Command-Line Interface) for AT commands + [ ] Enable print RAW format AT command communication data + (128) The maximum length of AT Commands buffer ``` 添加配置完成之后可以使用命令行重新生成工程，或使用 scons 来进行编译生成。 diff --git a/rt-thread-version/rt-thread-standard/programming-manual/net/net_introduce.md b/rt-thread-version/rt-thread-standard/programming-manual/net/net_introduce.md index bc6a7d3c1e93bee5916783f03dba7c3d27aaf122..1bdee42caf26e4675bbb4bfec32f048312294d9c 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/net/net_introduce.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/net/net_introduce.md @@ -4,18 +4,16 @@ ![](./docs/Kconfig_file.png) -从图片中的信息也可以了解到，AT，Lwip，Netdev，Sal 这些我们相对熟悉的功能也位于该目录中。这四个基础组件，可以驱动的网络设备的种类多到各个方面。从有线网络的各种 ETH 的方式，带 PHY 的 enc28j60，纯接口的 RJ45，还有自带网络协议栈的 W5500都可以直接经过配置，通过我们的 net 组件实现设备联网的需求；除了有线网络的接入方式，无线网络的接入方式则更多，2G模块，3G模块，4G模块，Cat-1模块，Cat-4模块，NB-IOT模块，乃至 5G 模块这些依赖基站运营商的入网方式，例如 SIM800，EC20，AIR720，L610，N58，M5311 等，这些不同厂家，不同工作频率的模组均可以通过 NET 组件入网；WIFI 这种无需运营商直接提供的网络的入网方式，例如 ESP8266，W60x，rw007 等。 +从图片中的信息也可以了解到，AT，Lwip，Netdev，SAL 这些我们相对熟悉的功能也位于该目录中。这四个基础组件，可以驱动的网络设备的种类多到各个方面。从有线网络的各种 ETH 的方式，带 PHY 的 enc28j60，纯接口的 RJ45，还有自带网络协议栈的 W5500都可以直接经过配置，通过我们的 net 组件实现设备联网的需求；除了有线网络的接入方式，无线网络的接入方式则更多，2G模块，3G模块，4G模块，Cat-1模块，Cat-4模块，NB-IOT模块，乃至 5G 模块这些依赖基站运营商的入网方式，例如 SIM800，EC20，AIR720，L610，N58，M5311 等，这些不同厂家，不同工作频率的模组均可以通过 NET 组件入网；WIFI 这种无需运营商直接提供的网络的入网方式，例如 ESP8266，W60x，rw007 等。 -通过上面的简单介绍，大家应该可以基本了解 Net 组件的作用，即为使用 RT-Thread 的设备提供上网能力。上面的联网设备，品类繁多，方式各异，但其实追踪到依赖的基础 net 能力其实也没有多复杂。实际上大部分的功能依赖的基础能力，只有两组而已，即 AT ，Lwip；而到用户，也就开发者层面，大部分就只用到 Sal 这一个概念。 +通过上面的简单介绍，大家应该可以基本了解 Net 组件的作用，即为使用 RT-Thread 的设备提供上网能力。上面的联网设备，品类繁多，方式各异，但其实追踪到依赖的基础 net 能力其实也没有多复杂。实际上大部分的功能依赖的基础能力，只有两组而已，即 AT ，Lwip；而到用户，也就开发者层面，大部分就只用到 SAL 这一个概念。 ![](./docs/network_frame.jpg) -相信大家看过这份[文档](https://www.rt-thread.org/document/site/programming-manual/sal/sal/ )，主要描述了 Sal 提供的编程接口，也就是大家常用的 socket 接口；通过 Sal 接口大家已经可以实现 MQTT，NTP，TFTP，TCP Client，TCP Server，webclient，UDP Client，UDP Server，webnet 等这些大家经常会使用的工具。像浏览器一样访问网站，webclient；模拟一个网站，webnet；连接各种云平台，Mqtt；获取准确授时，NTP ；通过网络传输文件 ，TFTP ；诸如此类功能， Sal 提供了轻松访问网络的一把钥匙。你可以理解这把钥匙是向上的，但是这篇文章现在要讲的，是向下的，看看 Sal 这样组件，又是谁在支撑着它。 +相信大家看过这份[文档](../sal/sal.md)，主要描述了 SAL 提供的编程接口，也就是大家常用的 socket 接口；通过 SAL 接口大家已经可以实现 MQTT，NTP，TFTP，TCP Client，TCP Server，webclient，UDP Client，UDP Server，webnet 等这些大家经常会使用的工具。像浏览器一样访问网站，webclient；模拟一个网站，webnet；连接各种云平台，Mqtt；获取准确授时，NTP ；通过网络传输文件 ，TFTP ；诸如此类功能， SAL 提供了轻松访问网络的一把钥匙。你可以理解这把钥匙是向上的，但是这篇文章现在要讲的，是向下的，看看 SAL 这样组件，又是谁在支撑着它。 Net 组件的主要内容有 4 个方面，分别是 sal ，AT，lwip 与 netdev，我们先从 AT 和 Lwip 讲起，在不同的方式中介绍 sal 的用途；然后讲 netdev 的作用。 - - ### 1. 总概 对于一个给定的模组，他的联网方式有时并不是单一的；以常见的 Cat-4 (4G) 模块为例，一方面它可以使用 AT 命令这种经典的方式来实现网络连接；另一方面又可以通过 PPP 拨号，使用 lwip 的方式来实现网络连接。或者在以 W60x 为例，一方面可以使用 AT 的方式来实现联网功能；另一方面又可以使用裸 IP 包的方式来实现网络连接。**在选取上网模块时，应当考虑片上资源的情况，以及网络质量的问题，选择比较适合的联网方式。**条条大路通罗马，短途长途，步行开车还是有些小区别的。 @@ -36,7 +34,7 @@ RT-Thread 的 AT 组件的设计目的就是使设备能发送和解析 AT 命 * AT 命令用作模块控制 * AT 命令用作数据的解析 -对 AT Client 功能做大规模应用的软件包为 [at_device ](https://github.com/RT-Thread-packages/at_device)，作为一款使用频次很高的软件包，可以看到他充分利用了 AT 组件的能力，一方面针对模块控制的能力设置了 at_device_xxx.c 来提供模块的基础控制操作；一方面也提供了 at_socket_xxx.c 来提供数据解析能力。对于整体的 net 组件而言，at_socket_xxx.c 实际上沟通了 AT 组件与 Sal，使得上层应用能依赖 at_socket_xxx.c 的函数，实现对应的网络功能 MQTT，HTTP.... +对 AT Client 功能做大规模应用的软件包为 [at_device ](https://github.com/RT-Thread-packages/at_device)，作为一款使用频次很高的软件包，可以看到他充分利用了 AT 组件的能力，一方面针对模块控制的能力设置了 at_device_xxx.c 来提供模块的基础控制操作；一方面也提供了 at_socket_xxx.c 来提供数据解析能力。对于整体的 net 组件而言，at_socket_xxx.c 实际上沟通了 AT 组件与 SAL，使得上层应用能依赖 at_socket_xxx.c 的函数，实现对应的网络功能 MQTT，HTTP.... ```c static const struct sal_socket_ops at_socket_ops = @@ -100,7 +98,7 @@ struct at_socket_ops 除了这些使用 at_device 能搜索到的问题，还有一些因为使用了 at_device 而产生的问题；这些问题的出现，对于在使用 AT 组件时的使用体验影响是很大的。 -在遇到问题时，希望能小心得验证问题，尝试解决问题；在问题难以解决时，详细描述问题复现的场景，按照格式在论坛中提问。问题描述清晰，复现手段准确，更能吸引小伙伴们的参与，共同解决问题。 +在遇到问题时，希望能小心地验证问题，并尝试解决问题；在问题难以解决时，请详细描述问题复现的场景，按照格式在论坛中提问。问题描述清晰，复现手段准确，更能吸引小伙伴们的参与，共同解决问题。 ![](./docs/at_menuconfig.png) @@ -186,7 +184,7 @@ static const struct sal_netdb_ops wiz_netdb_ops = | LINK_UP / LINK_DOWN | 链路是否正常 | | INTERNET_UP / INTERNET_DOWN | 网络是否正常 | -* LINK_UP 的意义为链路是否正常，在 netdev 启用后，LINK_UP 是作为 PING 命令是否可用的关键。如果 为 LINK_DOWN ，PING 命令将禁用。毕竟，网线都没有连接，PING 命令不可以用也是合情合理的喽。**LINK_DOWN 状态下禁用 PING 命令很合理，但是如果 netdev 的状态被异常置为 LINK_DOWN 就很苦恼了。如果被代码错误执行到设置为 LINK_DOWN，PING 命令将不可用。**netdev 的使用，可以参考[文档介绍](https://www.rt-thread.org/document/site/programming-manual/netdev/netdev/)。 +* LINK_UP 的意义为链路是否正常，在 netdev 启用后，LINK_UP 是作为 PING 命令是否可用的关键。如果 为 LINK_DOWN ，PING 命令将禁用。毕竟，网线都没有连接，PING 命令不可以用也是合情合理的喽。**LINK_DOWN 状态下禁用 PING 命令很合理，但是如果 netdev 的状态被异常置为 LINK_DOWN 就很苦恼了。如果被代码错误执行到设置为 LINK_DOWN，PING 命令将不可用。**netdev 的使用，可以参考[文档介绍](../netdev/netdev.md)。 * INTERNET_UP 的意义为网络是否正常。实际上，RT-Thread 的代码逻辑中，把这个位作为标志位，但很少利用这个标志位做逻辑判断。这样做的原因，是因为判断 INTERNET_UP 的方式为访问 ```link.rt-thread.org```，如果能有回复，就把标志位置为 INTERNET_UP，否则置为 INTERNET_DOWN。这个逻辑在一般情况下算是正常，但是在一些网络拓扑中，很有可能被网络标记位不可达（被墙了，PS ：也有可能是 RT-Thread 的网络主机重启了），所以哪怕实际上是可以连接网络的，却显示为 INTERNET_DOWN。 除此以外，netdev 还有 PING 功能的抽象，就是上面提到的 LINK_DOWN 状态不可用的那个。说它是抽象，是因为 netdev 中并没有直接实现全部的 ping 逻辑，而是依赖底层的提供提供的 PING 能力。 diff --git a/rt-thread-version/rt-thread-standard/programming-manual/netdev/netdev.md b/rt-thread-version/rt-thread-standard/programming-manual/netdev/netdev.md index 742cee16723c882f5ffff8b5e6fa67e701b51bca..4e2c88ddcf7f570c79fc4cd3b5b64b33d22c3627 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/netdev/netdev.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/netdev/netdev.md @@ -85,14 +85,14 @@ netdev 相关的宏定义如下所示，使用时需要将对应宏定义添加 上面配置选项可以直接在 `rtconfig.h` 文件中添加使用，也可以通过组件包管理工具 ENV 配置选项加入，ENV 工具中具体配置路径如下： ```c -RT-Thread Components ---> - Network ---> - Network interface device ---> - [*] Enable network interface device - [*] Enable ifconfig features - [*] Enable ping features - [*] Enable netstat features - [*] Enable default netdev automatic change features + -> RT-Thread Components + -> Network + --- Enable network interface device + [*] Enable ifconfig features + -*- Enable ping features + [*] Enable netstat features + [*] Enable default netdev automatic change features + [ ] Enable IPV6 protocol support ``` 配置完成可以通过 scons 命令重新生成功能，完成 netdev 组件的添加。 diff --git a/rt-thread-version/rt-thread-standard/programming-manual/sal/sal.md b/rt-thread-version/rt-thread-standard/programming-manual/sal/sal.md index 1e0730ff773318e5cde67d58748835536dea900b..b59b97b3e503c7cfd7c9ed50c3238e31aef4dc5d 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/sal/sal.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/sal/sal.md @@ -235,15 +235,15 @@ MSH_CMD_EXPORT(sal_tls_test, SAL TLS function test); 上面配置选项可以直接在 `rtconfig.h` 文件中添加使用，也可以通过组件包管理工具 ENV 配置选项加入，ENV 工具中具体配置路径如下： ```c -RT-Thread Components ---> - Network ---> - Socket abstraction layer ---> - [*] Enable socket abstraction layer - protocol stack implement ---> - [ ] Support lwIP stack - [ ] Support AT Commands stack - [ ] Support MbedTLS protocol - [*] Enable BSD socket operated by file system API + -> RT-Thread Components + -> Network + --- SAL: socket abstraction layer + [*] Enable the ability that check internet status (NEW) + Docking with protocol stacks ---> + [ ] Docking with lwIP stack (NEW) + -*- Docking with AT commands stack + [ ] Docking with MbedTLS protocol (NEW) + (16) the maximum number of sockets (NEW) ``` 配置完成可以通过 scons 命令重新生成功能，完成 SAL 组件的添加。 diff --git a/rt-thread-version/rt-thread-standard/programming-manual/tls/tls.md b/rt-thread-version/rt-thread-standard/programming-manual/tls/tls.md index 8fa729966d54cc47f4b746e5fafae8916140ee23..bc8be1d3f58dfb2f8583a3625ccfe9a072b1db1a 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/tls/tls.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/tls/tls.md @@ -32,14 +32,16 @@ TLS 协议主要解决如下三个网络安全问题。 ![tls_ssl_version.png](./figure/tls_ssl_version.png) - ## 2.3 TLS 报文结构 TLS \(Transport Layer Security\)协议是由TLS 记录协议（TLS Record Protocol）和TLS 握手协议（TLS Handshake Protocol）这两层协议叠加而成的，位于底层的TLS 记录协议负责进行信息传输和认证加密，位于上层的TLS 握手协议则负责除加密以外的其它各种操作，比如密钥协商交换等。上层的TLS 握手协议又可以分为4个子协议，TLS 协议的层次结构如下图所示： + ![tls_http_layer.png](./figure/tls_http_layer.png) + 前面已经介绍了 TLS 协议的认证加密算法，这里先介绍 TLS 记录协议的报文结构，每一条 TLS 记录以一个短标头起始，标头包含记录内容的类型（或子协议)、协议版本和长度，消息数据紧跟在标头之后，如下图所示： ![tls_protocol.png](./figure/tls_protocol.png) + 了解了 TLS 记录报文结构，前面也介绍了认证加密过程，下面以 AES-GCM 为例，看看密文（消息明文 AES-CNT 加密而来，当不需要对消息加密时，此处保持明文即可）和 MAC（将序列号、标头等附加信息与密文一起通过 Galois-MAC 计算而来)是如何添加进 TLS 记录报文的： 上图中的几个字段作用如下： @@ -58,10 +60,15 @@ TLS \(Transport Layer Security\)协议是由TLS 记录协议（TLS Record Protoc 配置开启任意网络协议栈支持（如 lwIP 协议栈）； ![menuconfig_lwip_conf.png](./figure/menuconfig_lwip_conf.png) + 配置开启 MbedTLS 软件包（目前RT-Thread只支持 MbedTLS 类型加密方式）； + ![menuconfig_mbedtls_conf.png](./figure/menuconfig_mbedtls_conf.png) + 配置开启 SAL\_TLS 功能支持（如下配置选项章节所示）； + ![menuconfig_sal_tls_conf.png](./figure/menuconfig_sal_tls_conf.png) + 配置完成之后，只要在 socket 创建时传入的 protocol 类型使用 PROTOCOL\_TLS 或 **PROTOCOL\_DTLS** ，即可使用标准 BSD Socket API 接口，完成 TLS 连接的建立和数据的收发。示例代码如下所示： ```c @@ -364,8 +371,10 @@ static int webclient_get_comm(const char *uri) ``` ![http.png](./figure/http.png) + ![http.png](./figure/http_wireshark.png) -![http.png](./figure/http_protocol_message.png) + +![http.png](./figure/http_protocol_message.png) 4. webclient 抓包 https 协议，密文数据 @@ -383,5 +392,7 @@ static int webclient_get_comm(const char *uri) ``` ![http.png](./figure/https.png) + ![http.png](./figure/https_wireshark.png) + ![http.png](./figure/https_protocol_message.png) \ No newline at end of file