227 lines
6.2 KiB
Markdown
227 lines
6.2 KiB
Markdown
|
# CoAP Module
|
||
|
|
The CoAP module provides a simple implementation according to [CoAP](http://tools.ietf.org/html/rfc7252) protocol.
|
||
|
|
The basic endpoint server part is based on [microcoap](https://github.com/1248/microcoap), and many other code reference [libcoap](https://github.com/obgm/libcoap).
|
||
|
|
|
||
|
|
This Module implement both Client and Server side. GET/PUT/POST/DELETE is partially supported by Client. Server can regist Lua function and varibles. No Observe or Discover supported right now.
|
||
|
|
|
||
|
|
## Caution
|
||
|
|
CoAP Module is only in the very early stage and not complete right now.
|
||
|
|
|
||
|
|
## Constants
|
||
|
|
`coap.CON`, `coap.NON` is the request type.
|
||
|
|
|
||
|
|
`coap.TEXT_PLAIN`, `coap.LINKFORMAT`, `coap.XML`, `coap.OCTET_STREAM`, `coap.EXI`, `coap.JSON` is the content type.
|
||
|
|
|
||
|
|
## coap.Client()
|
||
|
|
|
||
|
|
Creates a CoAP client.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.Client()`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
none
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
CoAP client
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
cc = coap.Client()
|
||
|
|
-- assume there is a coap server at ip 192.168.100
|
||
|
|
cc:get(coap.CON, "coap://192.168.18.100:5683/.well-known/core")
|
||
|
|
-- GET is not complete, the result/payload only print out in console.
|
||
|
|
cc:post(coap.NON, "coap://192.168.18.100:5683/", "Hello")
|
||
|
|
```
|
||
|
|
|
||
|
|
## coap.Server()
|
||
|
|
|
||
|
|
Creates a CoAP server.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.Server()`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
none
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
CoAP server
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
-- use copper addon for firefox
|
||
|
|
cs=coap.Server()
|
||
|
|
cs:listen(5683)
|
||
|
|
|
||
|
|
myvar=1
|
||
|
|
cs:var("myvar") -- get coap://192.168.18.103:5683/v1/v/myvar will return the value of myvar: 1
|
||
|
|
|
||
|
|
all='[1,2,3]'
|
||
|
|
cs:var("all", coap.JSON) -- sets content type to json
|
||
|
|
|
||
|
|
-- function should tack one string, return one string.
|
||
|
|
function myfun(payload)
|
||
|
|
print("myfun called")
|
||
|
|
respond = "hello"
|
||
|
|
return respond
|
||
|
|
end
|
||
|
|
cs:func("myfun") -- post coap://192.168.18.103:5683/v1/f/myfun will call myfun
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
# CoAP Client
|
||
|
|
|
||
|
|
|
||
|
|
## coap.client:get()
|
||
|
|
|
||
|
|
Issue a GET request to the server.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.client:get( type, uri, payload )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `type` coap.CON, coap.NON, default to CON. when type is CON, and request failed, the request will retry another 4 times before giving up.
|
||
|
|
- `uri` the uri such as coap://192.168.18.103:5683/v1/v/myvar, only IP is supported.
|
||
|
|
- `payload` optional, the payload will be put in the payload section of the request.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
## coap.client:put()
|
||
|
|
|
||
|
|
Issue a PUT request to the server.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.client:put( type, uri, payload )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `type` coap.CON, coap.NON, default to CON. when type is CON, and request failed, the request will retry another 4 times before giving up.
|
||
|
|
- `uri` the uri such as coap://192.168.18.103:5683/v1/v/myvar, only IP is supported.
|
||
|
|
- `payload` optional, the payload will be put in the payload section of the request.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
## coap.client:post()
|
||
|
|
|
||
|
|
Issue a POST request to the server.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.client:post( type, uri, payload )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `type` coap.CON, coap.NON, default to CON. when type is CON, and request failed, the request will retry another 4 times before giving up.
|
||
|
|
- `uri` the uri such as coap://192.168.18.103:5683/v1/v/myvar, only IP is supported.
|
||
|
|
- `payload` optional, the payload will be put in the payload section of the request.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
## coap.client:delete()
|
||
|
|
|
||
|
|
Issue a DELETE request to the server.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.client:delete( type, uri, payload )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `type` coap.CON, coap.NON, default to CON. when type is CON, and request failed, the request will retry another 4 times before giving up.
|
||
|
|
- `uri` the uri such as coap://192.168.18.103:5683/v1/v/myvar, only IP is supported.
|
||
|
|
- `payload` optional, the payload will be put in the payload section of the request.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
|
||
|
|
# CoAP Server
|
||
|
|
|
||
|
|
|
||
|
|
## coap.server:listen()
|
||
|
|
|
||
|
|
Start the CoAP server on the given port.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.server:listen( port, ip )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `port` server port (number).
|
||
|
|
- `ip` optional.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
## coap.server:close()
|
||
|
|
|
||
|
|
Close the CoAP server.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.server:close( )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
none
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
## coap.server:var()
|
||
|
|
|
||
|
|
Regist a Lua variable as an endpoint in the server. the varible value then can be GET by a client via GET method, represented as an [URI](http://tools.ietf.org/html/rfc7252#section-6) to client. The endpoint path for varialble is '/v1/v/'.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.server:var( name, content_type )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `name` the Lua variable's name.
|
||
|
|
- `content_type` optional, default to coap.TEXT_PLAIN, see [Content Negotiation](http://tools.ietf.org/html/rfc7252#section-5.5.4)
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
-- use copper addon for firefox
|
||
|
|
cs=coap.Server()
|
||
|
|
cs:listen(5683)
|
||
|
|
|
||
|
|
myvar=1
|
||
|
|
cs:var("myvar") -- get coap://192.168.18.103:5683/v1/v/myvar will return the value of myvar: 1
|
||
|
|
-- cs:var(myvar), WRONG, this api accept the name string of the varialbe. but not the variable itself.
|
||
|
|
all='[1,2,3]'
|
||
|
|
cs:var("all", coap.JSON) -- sets content type to json
|
||
|
|
```
|
||
|
|
|
||
|
|
## coap.server:func()
|
||
|
|
|
||
|
|
Regist a Lua function as an endpoint in the server. the function then can be called by a client via POST method. represented as an [URI](http://tools.ietf.org/html/rfc7252#section-6) to client. The endpoint path for function is '/v1/f/'.
|
||
|
|
|
||
|
|
When the client issues a POST request to this URI, the payload will be passed to the function as parameter. the function's return value will be the payload in the message to the client.
|
||
|
|
|
||
|
|
The function registed SHOULD be accept ONLY ONE string type parameter, and return ONE string value or return nothing.
|
||
|
|
When the client issue
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
`coap.server:func( name, content_type )`
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `name` the Lua function's name.
|
||
|
|
- `content_type` optional, default to coap.TEXT_PLAIN, see [Content Negotiation](http://tools.ietf.org/html/rfc7252#section-5.5.4)
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
-- use copper addon for firefox
|
||
|
|
cs=coap.Server()
|
||
|
|
cs:listen(5683)
|
||
|
|
|
||
|
|
-- function should take only one string, return one string.
|
||
|
|
function myfun(payload)
|
||
|
|
print("myfun called")
|
||
|
|
respond = "hello"
|
||
|
|
return respond
|
||
|
|
end
|
||
|
|
cs:func("myfun") -- post coap://192.168.18.103:5683/v1/f/myfun will call myfun
|
||
|
|
-- cs:func(myfun), WRONG, this api accept the name string of the function. but not the function itself.
|
||
|
|
```
|