Go-CoAP

The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained networks in the Internet of Things. The protocol is designed for machine-to-machine (M2M) applications such as smart energy and building automation.

The go-coap provides servers and clients for DTLS, TCP-TLS, UDP, TCP in golang language.

Features

• CoAP over UDP RFC 7252.
• CoAP over TCP/TLS RFC 8232
• Observe resources in CoAP RFC 7641
• Block-wise transfers in CoAP RFC 7959
• request multiplexer
• multicast
• CoAP NoResponse option in CoAP RFC 7967
• CoAP over DTLS pion/dtls
• Too many requests response code RFC 8516

Requirements

• Go 1.24 or higher

Samples

Simple

Server UDP/TCP

    // Server

    // Middleware function, which will be called for each request.
    func loggingMiddleware(next mux.Handler) mux.Handler {
        return mux.HandlerFunc(func(w mux.ResponseWriter, r *mux.Message) {
            log.Printf("ClientAddress %v, %v\n", w.Conn().RemoteAddr(), r.String())
            next.ServeCOAP(w, r)
        })
    }

    // See /examples/simple/server/main.go
    func handleA(w mux.ResponseWriter, req *mux.Message) {
        err := w.SetResponse(codes.GET, message.TextPlain, bytes.NewReader([]byte("hello world")))
        if err != nil {
            log.Printf("cannot set response: %v", err)
        }
    }

    func main() {
        r := mux.NewRouter()
        r.Use(loggingMiddleware)
        r.Handle("/a", mux.HandlerFunc(handleA))
        r.Handle("/b", mux.HandlerFunc(handleB))

        log.Fatal(coap.ListenAndServe("udp", ":5688", r))


        // for tcp
        // log.Fatal(coap.ListenAndServe("tcp", ":5688",  r))

        // for tcp-tls
        // log.Fatal(coap.ListenAndServeTLS("tcp", ":5688", &tls.Config{...}, r))

        // for udp-dtls (deprecated: *dtls.Config is deprecated in pion/dtls v3, prefer options-based API)
        // log.Fatal(coap.ListenAndServeDTLS("udp", ":5688", &dtls.Config{...}, r))

        // for udp-dtls (options-based API — pion/dtls v3)
        // log.Fatal(coap.ListenAndServeDTLS("udp", ":5688",
        //     net.NewDTLSServerOptions(dtls.WithPSK(...), dtls.WithCertificates(...)), r))
    }

Client

    // Client
    // See /examples/simpler/client/main.go
    func main() {
        co, err := udp.Dial("localhost:5688")

        // for tcp
        // co, err := tcp.Dial("localhost:5688")

        // for tcp-tls
        // co, err := tcp.Dial("localhost:5688", tcp.WithTLS(&tls.Config{...}))

        // for dtls (deprecated: *dtls.Config is deprecated in pion/dtls v3, prefer options-based API)
        // co, err := dtls.Dial("localhost:5688", &dtls.Config{...})

        // for dtls (options-based API — pion/dtls v3)
        // co, err := dtls.Dial("localhost:5688",
        //     dtlscoap.NewDTLSClientOptions(piondtls.WithPSK(...), piondtls.WithCertificates(...)))

        if err != nil {
            log.Fatalf("Error dialing: %v", err)
        }
        ctx, cancel := context.WithTimeout(context.Background(), time.Second)
        defer cancel()
        resp, err := co.Get(ctx, "/a")
        if err != nil {
            log.Fatalf("Cannot get response: %v", err)
            return
        }
        log.Printf("Response: %+v", resp)
    }

DTLS Options-based API (pion/dtls v3)

Deprecation notice: *dtls.Config is deprecated in pion/dtls v3 in favour of immutable options-based configurations. Its use in go-coap is consequently deprecated as well and may be removed in a future major version. Migrate to net.NewDTLSServerOptions / dtls.NewDTLSClientOptions as shown below.

In addition to the legacy *dtls.Config, go-coap supports the options-based API introduced in pion/dtls v3. Both approaches are currently accepted by the same generic functions (ListenAndServeDTLS, Dial, NewDTLSListener).

Use net.NewDTLSServerOptions(...) / dtls.NewDTLSClientOptions(...) to compose DTLS configurations from individual options:

import (
    coap   "github.com/plgd-dev/go-coap/v3"
    coapnet "github.com/plgd-dev/go-coap/v3/net"
    coapdtls "github.com/plgd-dev/go-coap/v3/dtls"
    piondtls "github.com/pion/dtls/v3"
)

// Server
serverOpts := coapnet.NewDTLSServerOptions(
    piondtls.WithPSK(func(hint []byte) ([]byte, error) {
        return []byte{0xAB, 0xC1, 0x23}, nil
    }),
    piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
)
log.Fatal(coap.ListenAndServeDTLS("udp", ":5688", serverOpts, r))

// Client
clientOpts := coapdtls.NewDTLSClientOptions(
    piondtls.WithPSK(func(hint []byte) ([]byte, error) {
        return []byte{0xAB, 0xC1, 0x23}, nil
    }),
    piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
)
co, err := coapdtls.Dial("localhost:5688", clientOpts)

See examples/options/server/ and examples/options/client/ for complete working examples using the options-based API.

Observe / Notify

Server example.

Client example.

Multicast

Server example.

Client example.

License

Apache 2.0

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site.

Backers

Become a backer and get your image on our README on Github with a link to your site.