CoAP Shell 笔记

1. 概述

CoAP (Constrained Application Protocol) 是一种专为物联网 (IoT) 中资源受限的节点和网络设计的 RESTful Web 传输协议。CoAP Shell 是一个基于命令行的交互式工具，用于与支持 CoAP 的服务器进行交互。

2. 主要功能

协议支持：
- 支持 coap: 和 coaps: 协议（分别对应 UDP 和 DTLS 传输）。
- 提供 DTLS 会话管理，确保数据传输的安全性。
CoAP 方法：
- 支持标准的 CoAP 方法：
  - GET: 获取资源
  - PUT: 更新资源
  - POST: 创建资源
  - DELETE: 删除资源
高级功能：
- 资源观察 (Observing): 允许客户端订阅资源的变化，服务器会在资源发生变化时通知客户端。
- 资源发现 (Discovery): 允许客户端发现服务器上的可用资源，并支持基于 href, ct, rt, obs 等参数的过滤。
- 消息交换模式：
  - 同步模式: 客户端发送请求后等待服务器响应。
  - 异步模式 (--async): 客户端发送请求后不等待服务器响应，继续执行其他操作。
- 消息类型：
  - 可确认消息 (Confirmable): 需要服务器确认的可靠消息。
  - 不可确认消息 (Non-Confirmable): 不需要服务器确认的消息。
用户友好性：
- TAB 自动补全: 支持命令和参数的自动补全，提高使用效率。
- 详细帮助文档: 输入 help 可查看所有可用命令及其使用说明。
安全性：
- 支持可插拔的密钥/信任存储和凭证管理，确保与服务器通信的安全性。
集成与扩展：
- 基于 Spring Shell, Californium (Cf) 和 Scandium (Sc) 项目构建。
- 作为 SpringBoot 应用打包成单个可执行的 JAR 文件，可在任何 Java 8+ 环境中运行。
IKEA TRÅDFRI 网关支持：
- 提供对 IKEA TRÅDFRI 智能照明系统的基本支持，包括：
  - 注册新账户并生成预共享密钥 (PSK)。
  - 列出连接的设备及其状态。
  - 控制设备开关，例如打开或关闭灯泡。
  - 使用 CoAP 的 PUT 方法发送 JSON 负载来控制设备属性，例如设置 5850 属性为 1 打开灯泡，设置为 0 关闭灯泡。

3. 使用指南

3.1 快速启动

1.获取 CoAP Shell:

下载预构建的 coap-shell.jar 文件，或按照下文说明自行构建。

2.启动 CoAP Shell:

java -jar ./coap-shell-1.1.1.jar

启动后，会出现类似以下的提示符：

  _____     ___   ___     ______       ____/ ___/__  / _ | / _ \   / __/ /  ___ / / /
/ /__/ _ \/ __ |/ ___/  _\ \/ _ \/ -_) / /
\___/\___/_/ |_/_/     /___/_//_/\__/_/_/
CoAP Shell (v1.1.1)
For assistance hit TAB or type "help".
server-unknown:>

3.连接到 CoAP 服务器:

server-unknown:>connect coap://californium.eclipse.org
available
coap://californium.eclipse.org/:>

常见的 CoAP 服务器地址示例：
- coap://californium.eclipse.org/
- coap://coap.me

3.2 常用命令

资源发现:
```
coap://californium.eclipse.org/:>discover --query href=/*
```
- 该命令会列出服务器上所有可用资源，并显示其路径、类型、内容类型、接口、大小和可观察性等信息。
获取资源:
```
coap://californium.eclipse.org/:>get /multi-format --accept application/xml
```
- 该命令获取指定路径的资源，并指定接受的内容类型为 application/xml。
控制 IKEA TRÅDFRI 设备:
1.
生成预共享密钥 (PSK):
```
server-unknown:>ikea gateway key --ip 192.168.178.151 --identity myIkeaGatewayIdentity --security-code <Gateway Code Label>
```
- 替换 <Gateway Code Label> 为网关背面的安全码。
- 该命令会返回生成的 IDENTITY 和 PRE_SHARED_KEY，需要妥善保存。
2.
连接到 IKEA 网关:
```
server-unknown:>connect coaps://192.168.178.151:5684 --identity myIkeaGatewayIdentity --secret X5xyYM41qFS7vN10
available
coaps://192.168.178.151:5684:>
```
- 替换 192.168.178.151 为网关的 IP 地址。
3.
列出连接的设备:
```
coaps://192.168.178.151:5684:>ikea device list
```
- 该命令会列出所有连接的设备及其状态，例如灯泡的开关状态。
4.
控制设备开关:
- 打开灯泡:
```
coaps://192.168.178.151:5684:>ikea turn on --instance 65539
```
- 关闭灯泡:
```
coaps://192.168.178.151:5684:>ikea turn off --instance 65539
```
- 替换 65539 为目标设备的实例 ID。
5.
使用 PUT 方法控制设备属性:
- 打开灯泡:
```
coaps://192.168.178.151:5684:>put //15001/65539 --payload '{"3311":[{"5850":1}]}'
```
- 关闭灯泡:
```
coaps://192.168.178.151:5684:>put //15001/65539 --payload '{"3311":[{"5850":0}]}'
```
- 这里的 //15001/65539 是设备的 URI 模板，15001 是设备对象 ID，65539 是设备实例 ID。

4. 注意事项

DTLS 会话过期: 如果出现 org.eclipse.californium.elements.EndpointMismatchException 错误，说明 DTLS 会话已过期，需要重新连接。
日志调试: 启动 CoAP Shell 时，可以使用 --logging.level 参数来设置日志级别，例如：
```
java -jar ./target/coap-shell-1.1.1-SNAPSHOT.jar --logging.level.org.eclipse.californium=DEBUG
```
- 这对于调试 CoAP 请求消息和 DTLS 交互非常有用。