README
¶
Mainflux CoAP Adapter
Mainflux CoAP adapter provides an CoAP API for sending messages through the platform.
Configuration
The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.
| Variable | Description | Default |
|---|---|---|
MF_COAP_ADAPTER_PORT |
Service listening port | 5683 |
MF_BROKER_URL |
Message broker instance URL | nats://localhost:4222 |
MF_COAP_ADAPTER_LOG_LEVEL |
Service log level | error |
MF_COAP_ADAPTER_CLIENT_TLS |
Flag that indicates if TLS should be turned on | false |
MF_COAP_ADAPTER_CA_CERTS |
Path to trusted CAs in PEM format | |
MF_COAP_ADAPTER_PING_PERIOD |
Hours between 1 and 24 to ping client with ACK message | 12 |
MF_JAEGER_URL |
Jaeger server URL for distributed tracing. Leave empty to disable tracing. | |
MF_THINGS_AUTH_GRPC_URL |
Things service Auth gRPC URL | localhost:8183 |
MF_THINGS_AUTH_GRPC_TIMEOUT |
Things service Auth gRPC request timeout in seconds | 1s |
Deployment
The service itself is distributed as Docker container. Check the coap-adapter service section in docker-compose to see how service is deployed.
Running this service outside of container requires working instance of the message broker service. To start the service outside of the container, execute the following shell script:
# Download the latest version of the service
git clone https://github.com/MainfluxLabs/mainflux
cd mainflux
# compile the http
make coap
# Copy binary to bin
make install
# set the environment variables and run the service
MF_BROKER_URL=[Message broker instance URL] \
MF_COAP_ADAPTER_PORT=[Service HTTP port] \
MF_COAP_ADAPTER_LOG_LEVEL=[Service log level] \
MF_COAP_ADAPTER_CLIENT_TLS=[Flag that indicates if TLS should be turned on] \
MF_COAP_ADAPTER_CA_CERTS=[Path to trusted CAs in PEM format] \
MF_COAP_ADAPTER_PING_PERIOD: [Hours between 1 and 24 to ping client with ACK message] \
MF_JAEGER_URL=[Jaeger server URL] \
MF_THINGS_AUTH_GRPC_URL=[Things service Auth gRPC URL] \
MF_THINGS_AUTH_GRPC_TIMEOUT=[Things service Auth gRPC request timeout in seconds] \
$GOBIN/mainfluxlabs-coap
Usage
Since CoAP protocol does not support Authorization header (option) and since options have a limited size, authentication is supplied in the form of URI Query parameters:
auth- Thing authentication key
type- Type of Thing key. One of:
external,internal.
- Type of Thing key. One of:
Publishing messages
To publish a message to a thing, optionally with a subtopic:
coap://localhost/things/<thing_id>/messages?auth=<thing_key>&type=<key_type>
coap://localhost/things/<thing_id>/messages/<subtopic>?auth=<thing_key>&type=<key_type>
The publisher is determined by the auth key, not the path.
Sending commands
To send a command to a specific thing (M2M, authorized by publisher thing key):
coap://localhost/things/<thing_id>/commands?auth=<thing_key>&type=<key_type>
To send a command to all things in a group:
coap://localhost/groups/<group_id>/commands?auth=<thing_key>&type=<key_type>
Both endpoints support an optional subtopic:
coap://localhost/things/<thing_id>/commands/<subtopic>?auth=<thing_key>&type=<key_type>
coap://localhost/groups/<group_id>/commands/<subtopic>?auth=<thing_key>&type=<key_type>
Commands use POST (same as publishing messages). The publisher thing must have command permission over the target thing or group.
Documentation
¶
Overview ¶
Package coap contains the domain concept definitions needed to support Mainflux CoAP adapter service functionality. All constant values are taken from RFC, and could be adjusted based on specific use case.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrOption = errors.New("unable to set option")
ErrOption indicates an error when adding an option.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// In CoAP terminology, Token similar to the Session ID.
Token() string
Handle(subject string, m protomfx.Message) error
Cancel() error
Done() <-chan struct{}
}
Client wraps CoAP client.
type Service ¶
type Service interface {
// Publish Message
Publish(ctx context.Context, key domain.ThingKey, msg protomfx.Message) error
// Subscribe subscribes to profile with specified id, subtopic and adds subscription to
// service map of subscriptions under given ID.
Subscribe(ctx context.Context, key domain.ThingKey, subtopic string, c Client) error
// Unsubscribe method is used to stop observing resource.
Unsubscribe(ctx context.Context, key domain.ThingKey, subtopic, token string) error
// SendCommandToThing publishes a command to the specified thing, authorized by publisher thing key (M2M).
SendCommandToThing(ctx context.Context, key domain.ThingKey, thingID string, msg protomfx.Message) error
// SendCommandToGroup publishes a command to a group, authorized by publisher thing key (M2M).
SendCommandToGroup(ctx context.Context, key domain.ThingKey, groupID string, msg protomfx.Message) error
}
Service specifies CoAP service API.
Source Files
Directories