{"id":22054242,"url":"https://github.com/kb2ma/device-coap-c-pre-holding","last_synced_at":"2025-03-23T15:48:55.765Z","repository":{"id":67553118,"uuid":"289498086","full_name":"kb2ma/device-coap-c-pre-holding","owner":"kb2ma","description":"EdgeX device service for CoAP-based REST protocol","archived":false,"fork":false,"pushed_at":"2020-10-11T12:42:53.000Z","size":124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-28T21:46:43.298Z","etag":null,"topics":["coap","edge","edgex","iot","libcoap"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kb2ma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-22T13:59:25.000Z","updated_at":"2020-10-15T16:33:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"b0b53d57-52ac-44b2-a0cd-52524d1a736a","html_url":"https://github.com/kb2ma/device-coap-c-pre-holding","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kb2ma%2Fdevice-coap-c-pre-holding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kb2ma%2Fdevice-coap-c-pre-holding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kb2ma%2Fdevice-coap-c-pre-holding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kb2ma%2Fdevice-coap-c-pre-holding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kb2ma","download_url":"https://codeload.github.com/kb2ma/device-coap-c-pre-holding/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245127939,"owners_count":20565203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coap","edge","edgex","iot","libcoap"],"created_at":"2024-11-30T15:20:08.978Z","updated_at":"2025-03-23T15:48:55.756Z","avatar_url":"https://github.com/kb2ma.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# device-coap-c\n\nEdgeX device service for CoAP-based REST protocol\n\nThis device service allows a 3rd party sensor application to push data into EdgeX via CoAP. Like HTTP, CoAP provides REST based access to resources, but CoAP is more compact for use in constrained IoT devices.\n\nThe device-coap-c service (_device-coap_ for short) is modeled after the HTTP based [device-rest-go](https://github.com/edgexfoundry/device-rest-go) service, and runs over UDP. The current implementation is meant for one-way communication from a device into EdgeX by posting readings asynchronously. Synchronous interaction initiated by EdgeX can be added in the future.\n\ndevice-coap uses DTLS for secure communication to devices. It is written in C, and relies on the well known [libcoap](https://libcoap.net/) library.\n\n\n## Resources\n\ndevice-coap creates a parameterized CoAP resource to which data may be posted:\n\n```\n   /a1r/{deviceName}/{resourceName}\n```\n\n- `a1r` is short for \"API v1 resource\", as defined by device-rest-go.\n- `deviceName` refers to a `device` managed by the CoAP device service. For example, `res/configuration.toml` pre-defines a device named 'd1'.\n- `resourceName` refers to a `deviceResource` defined in the device profile, as described in the sub-section below.\n\nPayload data posted to one of these resources is type validated, and the resulting value then is sent into EdgeX via the Device SDK's asynchronous `post_readings` capability.\n\n## Profiles\n\n[example-datatype.yaml](./res/example-datatype.yaml) defines  generic resources for data types. The table below shows the available resource names and correspondence with CoAP attributes. \n\nFor example, the 'int' resource name means that EdgeX provides a CoAP resource, `/a1r/{deviceName}/int`. This resource accepts an integer encoded as text, like `42`.\n\n| resourceName | Type   | EdgeX MediaType\u003cbr\u003eCoAP Content-Format|\n|---------|--------|---------------------------------------|\n| int     | Int32  | text/plain                            |\n| float   | Float64| text/plain                            |\n| json    | String | application/json                      |\n\n\u003e_Note:_ You must define the Content-Format option in the CoAP POST request. See the _Testing_ section below for example use.\n\n\n## Configuration\n\nThis section describes properties in [configuration.toml](./res/configuration.toml) as used by device-coap. See the _Configuration and Registry_ section of the EdgeX documentation for background.\n\n### Driver\n\nBelow are the recognized properties for the Driver section, followed by an example.\n\n| Key         | Value                                                                             |\n|-------------|-----------------------------------------------------------------------------------|\n| CoapBindAddr| Address on which CoAP server listens for devices                                  |\n| SecurityMode| DTLS client-server security type. Does not support raw public key or certificates.|\n| PskKey      | Pre-shared key. Accepts only a single key, ignored in NoSec mode.                 |\n\n\n```\n[Driver]\n  # Supports IPv4 or IPv6 if provided by network infrastructure. Use '0.0.0.0'\n  # for any IPv4 interface, or '::' for any IPv6 interface.\n  CoapBindAddr = '0.0.0.0'\n  # Choose 'PSK' or 'NoSec'\n  SecurityMode = 'PSK'\n  # Key is up to 16 arbitrary bytes; must be base64 encoded here\n  PskKey = 'ME42aURHZ3Uva0Y0eG9lZw=='\n```\n\n### DeviceList\nThe `DeviceList` section pre-defines the 'd1' device.\n\n```toml\n# Pre-define Devices\n[[DeviceList]]\n  Name = 'd1'\n  Profile = 'Coap-Device'\n  Description = 'Coap Data Generator Device'\n  Labels = [ \"coap\", \"rest\" ]\n  [DeviceList.Protocols]\n    [DeviceList.Protocols.other]\n```\n\n## Docker Integration\n\n### Building\n\nYou can build a Docker image with the command below from the top level directory of a device-coap checkout.\n\n```\n   $ make docker\n```\n\n### Compose\n\nBelow is an example entry for a docker-compose template with the rest of the EdgeX setup. The CoAP server listens on the default secure port, 5684. It also listens on any interface since the CoAP message likely arrives from an external network.\n\n```\n  device-coap:\n    image: kb2ma/docker-device-coap-c:0.2-dev\n    ports:\n      - \"127.0.0.1:49750:49750\"\n      - \"0.0.0.0:5684:5684/udp\"\n    container_name: kb2ma-device-coap\n    hostname: kb2ma-device-coap\n    networks:\n      - edgex-network\n    environment:\n      \u003c\u003c: *common-variables\n      Service_Host: kb2ma-device-coap\n    depends_on:\n      - metadata\n      - data\n```\n\n## Testing/Simulation\n\nYou can use simulated data to test this service with libcoap's `coap-client` command line tool. The examples below are organized by the SecurityMode defined in the configuration.\n\n**NoSec**\n```\n   $ coap-client -m post -t 0 -e 1001 coap://127.0.0.1/a1r/d1/int\n```\n**PSK**\n```\n   $ coap-client -m post -u r17 -k 0N6iDGgu/kF4xoeg -t 0 -e 1001 coaps://127.0.0.1/a1r/d1/int\n```\n\n  * For DTLS PSK, a CoAP client must include a user identity via the `-u` option as well as the same key the server uses. Presently, the device-coap server does not evaluate the identity, only the key. Also, `coap-client` reads the key as a literal string, so characters must be readable from the command line. Finally, notice the protocol in the address is `coaps`. This protocol uses UDP port 5684 rather than 5683 for protocol `coap`.\n\n  * POSTing a text integer value will set the  `Value` of the `Reading` in EdgeX to the string representation of the value as an `Int32`. The POSTed value is verified to be a valid `Int32` value.\n\n  * A 400 error will be returned if the POSTed value fails the `Int32` type verification.\n\n### Zephyr CoAP client\n\nAlso see my Zephyr based [edgex-coap-peer](https://github.com/kb2ma/edgex-coap-peer) repository for a simple CoAP client usable on an IoT device. The client posts integer data for the example profile above, to `/a1r/d1/int`.\n\n### RIOT CoAP client\n\nAlso see my RIOT based [riot-edgex-coap-client](https://github.com/kb2ma/riot-edgex-coap-client) repository for a more realistic CoAP client. The client posts a temperature measurement from a sensor every 60 seconds to `/a1r/d1/float`.\n\n## Development\n\nThis section describes how to build and run a device-coap executable independent from Docker, for development or debugging.\n\n### Building\n\ndevice-coap depends on libcoap and tinydtls. See [build_deps.sh](scripts/build_deps.sh) to download and build them. As with any C based EdgeX device project, device-coap also depends on the EdgeX [C SDK](https://github.com/edgexfoundry/device-sdk-c/blob/master) for its SDK library and headers. Finally, see [build.sh](scripts/build.sh) and [build_debug.sh](scripts/build_debug.sh) to build device-coap itself. These scripts may be invoked via `make build` and `make build-debug` respectively.\n\n### Running\n\nSimply run the generated executable. The example below was built with the `build_debug.sh` script.\n\n```\n   $ build/debug/device-coap -f configuration-native.toml\n```\n\n\u003e_Note:_ Service configuration in `configuration-native.toml` is customized for a separate device-coap executable. Uses '172.17.0.1' for the `Service-\u003eHost` parameter. Uses 'localhost' for the `Host` parameter in the `Registry` and `Clients` sections.\n\nRun with `-h` to see all command line options.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkb2ma%2Fdevice-coap-c-pre-holding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkb2ma%2Fdevice-coap-c-pre-holding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkb2ma%2Fdevice-coap-c-pre-holding/lists"}