Merge pull request #943 from funshine/newdocs
add a doc for coap module
This commit is contained in:
Marcel Stör
commit
8cbc5d6a05
|
|
@ -0,0 +1,226 @@
|
|||
# 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.
|
||||
```
|
||||
|
|
@ -33,6 +33,7 @@ pages:
|
|||
- 'bit': 'en/modules/bit.md'
|
||||
- 'bmp085': 'en/modules/bmp085.md'
|
||||
- 'cjson': 'en/modules/cjson.md'
|
||||
- 'coap': 'en/modules/coap.md'
|
||||
- 'crypto': 'en/modules/crypto.md'
|
||||
- 'dht': 'en/modules/dht.md'
|
||||
- 'enduser setup': 'en/modules/enduser-setup.md'
|
||||
|
|
|
|||
Loading…
Reference in New Issue