mirror of
https://github.com/espressif/openthread.git
synced 2026-08-06 10:47:46 +00:00
[docs] update coap(s) docs (#3795)
This commit is contained in:
Jonathan Hui
committed by
Jonathan Hui
Jonathan Hui
parent
d4063fe9b8
commit
6f679e8fb0
+2
-153
@@ -14,8 +14,8 @@ OpenThread test scripts use the CLI to execute test cases.
|
||||
* [childip](#childip)
|
||||
* [childmax](#childmax)
|
||||
* [childtimeout](#childtimeout)
|
||||
* [coap](#coap-start)
|
||||
* [coaps](#coaps-start-checkpeercert)
|
||||
* [coap](README_COAP.md)
|
||||
* [coaps](README_COAPS.md)
|
||||
* [commissioner](#commissioner-start-provisioningurl)
|
||||
* [contextreusedelay](#contextreusedelay)
|
||||
* [counters](#counters)
|
||||
@@ -232,157 +232,6 @@ Set the Thread Child Timeout value.
|
||||
Done
|
||||
```
|
||||
|
||||
### coap start
|
||||
|
||||
Starts the application coap service.
|
||||
|
||||
```bash
|
||||
> coap start
|
||||
Coap service started: Done
|
||||
```
|
||||
|
||||
### coap stop
|
||||
|
||||
Stops the application coap service.
|
||||
|
||||
```bash
|
||||
> coap stop
|
||||
Coap service stopped: Done
|
||||
```
|
||||
|
||||
### coap resource \[uri-path\]
|
||||
|
||||
Sets the URI-Path for the test resource.
|
||||
|
||||
```bash
|
||||
> coap resource test
|
||||
Resource name is 'test': Done
|
||||
> coap resource
|
||||
Resource name is 'test': Done
|
||||
```
|
||||
|
||||
### coap \<method\> \<address\> \<uri\> \[payload\] \[type\]
|
||||
|
||||
* method: CoAP method to be used (GET/PUT/POST/DELETE).
|
||||
* address: IP address of the CoAP server to query.
|
||||
* uri: URI String of the resource on the CoAP server.
|
||||
* payload: In case of PUT/POST/DELETE a payload can be encapsulated.
|
||||
* type: Switch between confirmable ("con") and non-confirmable (default).
|
||||
|
||||
```bash
|
||||
> coap get fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc test
|
||||
Sending coap message: Done
|
||||
Received coap request from [fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc]: GET
|
||||
coap response sent successfully!
|
||||
Received coap response with payload: 30
|
||||
> coap put fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc test non-con somePayload
|
||||
Sending coap message: Done
|
||||
Received coap request from [fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc]: PUT with payload: 73 6f 6d 65 50 61 79 6c 6f 61 64
|
||||
> coap put fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc test con 123
|
||||
Sending coap message: Done
|
||||
Received coap request from [fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc]: PUT with payload: 31 32 33
|
||||
coap response sent successfully!
|
||||
Received coap response
|
||||
```
|
||||
|
||||
### coaps start \<checkPeerCert\>
|
||||
|
||||
Starts the Application CoAP Secure Service.
|
||||
|
||||
* checkPeerCert: Peer Certificate Check can be disabled by typing false.
|
||||
|
||||
```bash
|
||||
> coaps start false
|
||||
Verify Peer Certificate: false. Coap Secure service started: Done
|
||||
> coaps start
|
||||
Verify Peer Certificate: true. Coap Secure service started: Done
|
||||
```
|
||||
|
||||
### coaps stop
|
||||
|
||||
Stops the Application CoAP Secure Service.
|
||||
|
||||
```bash
|
||||
> coaps stop
|
||||
Coap Secure service stopped: Done
|
||||
```
|
||||
|
||||
### coaps set psk \<preSharedKey\> \<keyIdentity\>
|
||||
|
||||
Set a pre-shared key with his identifier and the ciphersuite
|
||||
"DTLS_PSK_WITH_AES_128_CCM_8" for the dtls session.
|
||||
|
||||
* preSharedKey: The pre-shared key (PSK) for dtls session.
|
||||
* keyIdentity: The identifier for the PSK.
|
||||
|
||||
```bash
|
||||
> coaps set psk myPreSharedSecret myIdentifier
|
||||
Coap Secure set PSK: Done
|
||||
```
|
||||
|
||||
### coaps set x509
|
||||
|
||||
Set X.509 Certificate with his private key, which is saved in
|
||||
src/cli/x509_cert_key.hpp.
|
||||
|
||||
```bash
|
||||
> coaps set x509
|
||||
Coap Secure set own .X509 certificate: Done
|
||||
```
|
||||
|
||||
### coaps connect \<serverAddress\> \[port\]
|
||||
|
||||
Open a dtls session to a CoAP Secure Server.
|
||||
|
||||
* serverAddress: IPv6 address of Server
|
||||
|
||||
```bash
|
||||
> coaps connect 2001:1234::321
|
||||
Coap Secure connect: Done
|
||||
CoAP Secure connected!
|
||||
```
|
||||
|
||||
### coaps disconnect
|
||||
|
||||
Terminate the dtls session to the Server.
|
||||
|
||||
```bash
|
||||
> coaps disconnect
|
||||
CoAP Secure not connected or disconnected.
|
||||
Done
|
||||
```
|
||||
|
||||
### coaps \<method\> \<address\> \<uri\> \[type\] \[payload\]
|
||||
|
||||
* method: CoAP method to be used (GET/PUT/POST/DELETE).
|
||||
* address: IPv6 address of the CoAP Secure server to query.
|
||||
* uri: URI String of the resource on the CoAP server.
|
||||
* type: Switch between confirmable ("con") and non-confirmable (default).
|
||||
* payload: In case of PUT/POST/DELETE a payload can be encapsulated.
|
||||
|
||||
```bash
|
||||
> coaps get 2001:1234::321 secret
|
||||
Sending coap secure request: Done
|
||||
Received coap secure response
|
||||
CoapSecure RX Header Informations:
|
||||
Type 16 (NON CONF)
|
||||
Code 69 (Coap Code CONTENT)
|
||||
With payload (hex):
|
||||
4a756e2031322031353a30373a3336
|
||||
> coaps put 2001:1234::321 test non-con hello
|
||||
Sending coap secure request: Done
|
||||
> coaps post 2001:1234::321 test con
|
||||
Sending coap secure request: Done
|
||||
Received coap secure response
|
||||
CoapSecure RX Header Informations:
|
||||
Type 32 (NON CONF)
|
||||
Code 69 (Coap Code CONTENT)
|
||||
With payload (hex):
|
||||
4a756e2031322031353a30373a3336
|
||||
> coaps delete 2001:1234::321 test
|
||||
Sending coap secure request: Done
|
||||
```
|
||||
|
||||
### commissioner start \<provisioningUrl\>
|
||||
|
||||
Start the Commissioner role.
|
||||
|
||||
+199
-109
@@ -1,155 +1,245 @@
|
||||
# OpenThread CLI - COAPS Example
|
||||
# OpenThread CLI - CoAPS Example
|
||||
|
||||
The OpenThread CoAP Secure APIs may be invoked via the OpenThread CLI.
|
||||
The OpenThread CoAPS APIs may be invoked via the OpenThread CLI.
|
||||
|
||||
CoAP Secure use DTLS (over UDP) to make an end to end encrypted connection.
|
||||
## Quick Start
|
||||
|
||||
### For use PSK with AES128 CCM8
|
||||
### Build with CoAPS API support
|
||||
|
||||
Use the `COAPS=1` build switch to enable CoAPS API support.
|
||||
|
||||
1a. enter your psk and his identifier
|
||||
|
||||
```bash
|
||||
coaps set psk <yourPsk> <PskIdentifier>
|
||||
> ./bootstrap
|
||||
> make -f examples/Makefile-posix COAPS=1
|
||||
```
|
||||
|
||||
### For use ECDHE ECDSA with AES128 CCM8
|
||||
### Form Network
|
||||
|
||||
1b. set the private key and .X509 certificate stored in core/cli/x509_cert_key.hpp.
|
||||
|
||||
> _optional_: add your [own](#create-ec-private-key) X.509 certificate and private key to 'core/cli/x509_cert_key.hpp'.
|
||||
|
||||
```bash
|
||||
coaps set x509
|
||||
```
|
||||
Form a network with at least two devices.
|
||||
|
||||
## Start CoAPS Service (for Server and Client)
|
||||
### Configure DTLS ciphersuite.
|
||||
|
||||
CoAPS uses DTLS to establish a secure, end-to-end connection.
|
||||
|
||||
This example supports two ciphersuites:
|
||||
|
||||
* TLS_PSK_WITH_AES_128_CCM_8
|
||||
```bash
|
||||
> coaps psk <your-psk> <your-psk-id>
|
||||
Done
|
||||
```
|
||||
|
||||
* TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
|
||||
```bash
|
||||
> coaps x509
|
||||
Done
|
||||
```
|
||||
The X.509 certificate stored in `core/cli/x509_cert_key.hpp`.
|
||||
|
||||
### Node 1
|
||||
|
||||
On node 1, setup CoAPS server with resource `test-resource`.
|
||||
|
||||
2. start (init) the coaps api and starts listen on coaps port (5684)
|
||||
|
||||
```bash
|
||||
> coaps start
|
||||
Done
|
||||
> coaps resource test-resource
|
||||
Done
|
||||
```
|
||||
|
||||
## CoAP Secure Server
|
||||
|
||||
* add a coap resource to provide to a coap client
|
||||
|
||||
```bash
|
||||
coaps resource <coapUri>
|
||||
```
|
||||
|
||||
## Connect to a DTLS Server
|
||||
|
||||
* connect to a dtls server
|
||||
|
||||
```bash
|
||||
coaps connect <serversIp> (port, if not default)
|
||||
```
|
||||
|
||||
## CoAP Secure Client
|
||||
|
||||
* get a resource form the server
|
||||
### Node 2
|
||||
|
||||
```bash
|
||||
coaps get (serversIp) <coapUri> (Con/NotCon) (payload)
|
||||
> coaps start
|
||||
Done
|
||||
> coaps connect <peer-ip6-address>
|
||||
Done
|
||||
coaps connected
|
||||
> coaps get test-resource
|
||||
Done
|
||||
coaps response from [fdde:ad00:beef:0:9903:14b:27e0:5744] with payload: 68656c6c6f576f726c6400
|
||||
> coaps put test-resource con payload
|
||||
Done
|
||||
coaps response from [fdde:ad00:beef:0:9903:14b:27e0:5744]
|
||||
```
|
||||
|
||||
> post, put and delete also possible
|
||||
|
||||
|
||||
<> must
|
||||
() opt
|
||||
|
||||
|
||||
## Complete example for DTLS/CoAP server (Node 1)
|
||||
### Result
|
||||
|
||||
In this example the coap server is also the dtls server.
|
||||
The dtls server waits for incoming connection on coaps port 5684.
|
||||
The [Node 2](#complete-example-dtlscoap-client-node-2) below is able to connect to this coaps server.
|
||||
|
||||
> Note: Node 1 and Node 2 must use the same mode. Either PSK or Certificate based.
|
||||
|
||||
```
|
||||
Node 1
|
||||
---------
|
||||
|CoAPS |
|
||||
|Server | <--Listen on Port 5684-- (Node 2)
|
||||
| |
|
||||
---------
|
||||
```
|
||||
|
||||
### with PSK
|
||||
On node 1, you should see output similar to below:
|
||||
|
||||
```bash
|
||||
coaps set psk secretPSK Client_identity
|
||||
coaps start
|
||||
coaps resource test
|
||||
coaps request from [fdde:ad00:beef:0:9e68:576f:714c:f395] GET
|
||||
coaps response sent
|
||||
coaps request from [fdde:ad00:beef:0:9e68:576f:714c:f395] PUT with payload: 7061796c6f6164
|
||||
coaps response sent
|
||||
```
|
||||
|
||||
### with Certificate
|
||||
## Generate Elliptic Curve Private Key and X.509 Certificate
|
||||
|
||||
### EC Private Key
|
||||
|
||||
```bash
|
||||
coaps set x509
|
||||
coaps start (false)
|
||||
coaps resource test
|
||||
> openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
|
||||
```
|
||||
|
||||
* param false: optional, disables peer certificate validation.
|
||||
|
||||
## Complete example DTLS/CoAP client (Node 2)
|
||||
|
||||
In this example the coap client is also the dtls client.
|
||||
The dlts client can connect to a coaps server which is listen on coaps port 5684, e.g to the [Node 1](#complete-example-for-dtlscoap-server-node-1) above.
|
||||
|
||||
> Note: Node 1 and Node 2 must use the same mode. Either PSK or Certificate based.
|
||||
|
||||
```
|
||||
Node 2
|
||||
---------
|
||||
|CoAPS |
|
||||
|Client |--Connect to Server on Port 5684--> (Node 1)
|
||||
| |
|
||||
---------
|
||||
```
|
||||
|
||||
### with PSK
|
||||
### X.509 Certificate
|
||||
|
||||
```bash
|
||||
coaps set psk secretPSK Client_identity
|
||||
coaps start
|
||||
coaps connect 2001:620:190:ffa1::321
|
||||
coaps get test
|
||||
coaps disconnect
|
||||
> openssl req -x509 -new -key ec_private.pem -out x509_cert.pem -days 30
|
||||
```
|
||||
|
||||
### with Certificate
|
||||
## Command List
|
||||
|
||||
* [help](#help)
|
||||
* [connect](#connect-address)
|
||||
* [delete](#delete-uri-path-type-payload)
|
||||
* [disconnect](#disconnect)
|
||||
* [get](#get-uri-path-type)
|
||||
* [post](#post-uri-path-type-payload)
|
||||
* [psk](#psk-psk-pskid)
|
||||
* [put](#put-uri-path-type-payload)
|
||||
* [resource](#resource-uri-path)
|
||||
* [start](#start)
|
||||
* [stop](#stop)
|
||||
* [x509](#x509)
|
||||
|
||||
## Command Details
|
||||
|
||||
### help
|
||||
|
||||
```bash
|
||||
coaps set x509
|
||||
coaps start (false)
|
||||
coaps connect <server_ip>
|
||||
coaps get test
|
||||
coaps disconnect
|
||||
> coaps help
|
||||
help
|
||||
connect
|
||||
delete
|
||||
disconnect
|
||||
get
|
||||
post
|
||||
psk
|
||||
put
|
||||
resource
|
||||
start
|
||||
stop
|
||||
x509
|
||||
Done
|
||||
```
|
||||
|
||||
* param false: optional, disables peer certificate validation.
|
||||
List the CoAPS CLI commands.
|
||||
|
||||
## Create own Private Key with a .X509 Certificate
|
||||
### connect \<address\>
|
||||
|
||||
### Create EC Private Key
|
||||
Establish DTLS session.
|
||||
|
||||
* address: IPv6 address of the peer.
|
||||
|
||||
```bash
|
||||
openssl ecparam -genkey -out myECKey.pem -name prime256v1 -noout
|
||||
> coaps connect fdde:ad00:beef:0:9903:14b:27e0:5744
|
||||
Done
|
||||
coaps connected
|
||||
```
|
||||
|
||||
* ecparam: Key for Elliptic Curve Algorithms
|
||||
* -name: The elliptic curve to chose. a list of available curves `openssl ecparam -list_curves`
|
||||
* -noout: private key without EC Parameters
|
||||
### delete \<uri-path\> \[type\] \[payload\]
|
||||
|
||||
### Create .X509 Certificate
|
||||
* uri-path: URI path of the resource.
|
||||
* type: "con" for Confirmable or "non-con" for Non-confirmable (default).
|
||||
* payload: CoAPS request payload.
|
||||
|
||||
```bash
|
||||
openssl req -x509 -new -key myECKey.pem -out myX509Cert.pem -days 30
|
||||
> coaps delete test-resource con payload
|
||||
Done
|
||||
```
|
||||
|
||||
* -days: validity time of certificate
|
||||
### disconnect
|
||||
|
||||
```bash
|
||||
> coaps disconnect
|
||||
coaps disconnected
|
||||
Done
|
||||
```
|
||||
|
||||
### get \<uri-path\> \[type\]
|
||||
|
||||
* uri-path: URI path of the resource.
|
||||
* type: "con" for Confirmable or "non-con" for Non-confirmable (default).
|
||||
|
||||
```bash
|
||||
> coaps get test-resource
|
||||
Done
|
||||
```
|
||||
|
||||
### post \<uri-path\> \[type\] \[payload\]
|
||||
|
||||
* uri-path: URI path of the resource.
|
||||
* type: "con" for Confirmable or "non-con" for Non-confirmable (default).
|
||||
* payload: CoAPS request payload.
|
||||
|
||||
```bash
|
||||
> coaps post test-resource con payload
|
||||
Done
|
||||
```
|
||||
|
||||
### psk \<psk\> \<pskid\>
|
||||
|
||||
Set DTLS ciphersuite to `TLS_PSK_WITH_AES_128_CCM_8`.
|
||||
|
||||
* psk: pre-shared key
|
||||
* pskid: pre-shared key identifier
|
||||
|
||||
```bash
|
||||
> coaps psk 123 pskid
|
||||
Done
|
||||
```
|
||||
|
||||
### put \<uri-path\> \[type\] \[payload\]
|
||||
|
||||
* uri-path: URI path of the resource.
|
||||
* type: "con" for Confirmable or "non-con" for Non-confirmable (default).
|
||||
* payload: CoAPS request payload.
|
||||
|
||||
```bash
|
||||
> coaps put test-resource con payload
|
||||
Done
|
||||
```
|
||||
|
||||
### resource \[uri-path\]
|
||||
|
||||
Sets the URI path for the test resource.
|
||||
|
||||
```bash
|
||||
> coaps resource test-resource
|
||||
Done
|
||||
> coaps resource
|
||||
test-resource
|
||||
Done
|
||||
```
|
||||
|
||||
### start
|
||||
|
||||
Starts the application coaps service.
|
||||
|
||||
* checkPeerCert: Peer Certificate Check can be disabled by typing false.
|
||||
|
||||
```bash
|
||||
> coaps start
|
||||
Done
|
||||
```
|
||||
|
||||
### stop
|
||||
|
||||
Stops the application coaps service.
|
||||
|
||||
```bash
|
||||
> coaps stop
|
||||
Done
|
||||
```
|
||||
|
||||
### x509
|
||||
|
||||
Set DTLS ciphersuite to `TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8`.
|
||||
|
||||
The X.509 certificate stored in [`src/cli/x509_cert_key.hpp`](x509_cert_key.hpp).
|
||||
|
||||
```bash
|
||||
> coaps x509
|
||||
Done
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user