1# zoap23A WiP [CoAP][rfc 7252] implementation for bare-metal [constrained devices][rfc 7228] in [Zig][zig web].45## Status67Presently, the majority of the CoAP standard is not implemented.8However, creating a very basic CoAP server which sends and receives9non-confirmable messages is possible and already done as part of my10[zig-riscv-embedded][zig-riscv github] project. Since the code focus11on constrained bare-metal targets, it is optimized for a small memory12footprint and uses statically allocated fixed-size buffers instead of13performing dynamic memory allocation. Furthermore, it does not use any14OS-specific code from the Zig standard library (e.g. Sockets).1516The code is known to compile with Zig `0.9.1`.1718## Installation1920Zig packages are simply Zig source trees and are imported using21[`@import`][zig import] just like code from the Zig standard library.22Therefore, the zoap source tree must be added to the Zig codebase using23it. This can, for example, be achieved using [git submodules][git submodules]24or a third-party package manager like [gyro][gyro github].2526For the former method, the package source tree needs to be explicitly27added to `build.rs`. Assuming, the submodule was added as `./zoap` in28the directory root the following code should be sufficient:2930 exe.addPackage(std.build.Pkg{31 .name = "zoap",32 .path = "./zoap/src/zoap.zig",33 });3435Afterwards, simply import zoap using `const zoap = @import("zoap");`.3637## Usage3839As noted above, this library targets freestanding constrained devices.40For this reason, all memory is statically allocated. To implement a CoAP41server with zoap, the central data structure is the Dispatcher. This42Dispatcher takes a list of Resources and forwards incoming requests to43them if the URI in the request matches one of the available resources.44Both, the dispatcher and the resources need to be statically allocated,45e.g. as global variables:4647 const resources = &[_]zoap.Resource{48 .{ .path = "hello", .handler = helloHandler },49 .{ .path = "about", .handler = aboutHandler },50 };51 var dispatcher = zoap.Dispatcher{52 .resources = resources,53 };5455The code above allocates a dispatcher with two resources: `/hello` and56`/about`. An incoming CoAP request for either of those resources invokes57the associated handler function. The `helloHandler` implementation may58looks as follows:5960 pub fn helloHandler(resp: *zoap.Response, req: *zoap.Request) codes.Code {61 if (!req.header.code.equal(codes.GET))62 return codes.BAD_METHOD;6364 const w = resp.payloadWriter();65 w.writeAll("Hello, World!") catch {66 return codes.INTERNAL_ERR;67 };6869 return codes.CONTENT;70 }7172The function takes two parameters: The resulting CoAP response and the73incoming CoAP request. The handler returns the CoAP response code for74the incoming request. The implementation above first checks the request75method, if it doesn't match the expected method a response with a76Method Not Allowed status code is returned. Otherwise, the77`helloHandler` writes `Hello, World!` to the response body and, unless an78error occurs, it responses with a successful content response code.7980In order to invoke these handlers, incoming CoAP requests need to be81forwarded to the Dispatcher via the `Dispatcher.dispatch` method which82takes an incoming CoAP request as a parameter and forwards it to the83matching resource (if any). The method returns the appropriate CoAP84response. Since this library attempts to be OS-independent, the code for85retrieving incoming requests and sending responses to these requests86depends on your environment. For example, CoAP request may be read from87a UDP socket in a POSIX environment.8889For or a more detailed and complete usage example refer to90[zig-riscv-embedded][zig-riscv github] which reads incoming requests91from a [SLIP][rfc 1055] serial interface.9293## Test vectors9495For parsing code, test vectors are created using the existing96[go-coap][go-coap github] implementation written in [Go][go website].97Test vectors are generated using `./testvectors/generate.go` and98available as `./testvectors/*.bin` files. These files are tracked in the99Git repositories and thus Go is not necessarily needed to run existing100tests.101102Each Zig test case embeds this file via [`@embedFile`][zig embedFile].103All existing Zig parser test cases can be run using:104105 $ zig test src/packet.zig106107New test cases can be added by modifying `./testvectors/generate.go` and108`./src/packet.zig`. Afterwards, the test case files need to be109regenerated using:110111 $ cd ./testvectors && go build -trimpath && ./testvectors112113New test vectors must be committed to the Git repository.114115## License116117This program is free software: you can redistribute it and/or modify it118under the terms of the GNU Affero General Public License as published by119the Free Software Foundation, either version 3 of the License, or (at120your option) any later version.121122This program is distributed in the hope that it will be useful, but123WITHOUT ANY WARRANTY; without even the implied warranty of124MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero125General Public License for more details.126127You should have received a copy of the GNU Affero General Public License128along with this program. If not, see <https://www.gnu.org/licenses/>.129130[rfc 7252]: https://datatracker.ietf.org/doc/rfc7252/131[rfc 7228]: https://datatracker.ietf.org/doc/rfc7228/132[rfc 1055]: https://datatracker.ietf.org/doc/rfc1055/133[zig web]: https://ziglang.org/134[zig-riscv github]: https://github.com/nmeum/zig-riscv-embedded135[go-coap github]: https://github.com/plgd-dev/go-coap136[go website]: https://golang.org137[zig embedFile]: https://ziglang.org/documentation/0.9.1/#embedFile138[zig import]: https://ziglang.org/documentation/0.9.1/#import139[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules140[gyro github]: https://github.com/mattnite/gyro