22 CoAP Lab: Stack and Trace Contracts

22.8.1 Step 1: Start the CoAP resource on localhost

• In a project-local Python target or isolated environment, install aiocoap, then start the server code below in one terminal.
• Watch for CoAP server started on port 5683 and Resources: /temperature (GET, PUT) before opening a client terminal.
• In the local run here, an equivalent aiocoap resource bound to 127.0.0.1:56830 logged server GET token=... payload=b''; the site registration supplies /temperature.
• Keep the bind address and port in the run record; localhost proves an application exchange but no wireless link, DTLS, or remote reachability.
• The code below registers only /temperature; /config, /readings, and Observe need additional handlers before those clients can succeed.

import asyncio
from aiocoap import *
import aiocoap.resource as resource

class TemperatureResource(resource.Resource):
    """Example resource for temperature readings"""

    async def render_get(self, request):
        """Handle GET requests - returns current temperature"""
        temperature = 22.5  # Simulated sensor reading

        payload = f"{temperature}".encode('utf-8')

        return Message(
            code=Code.CONTENT,      # 2.05 Content (success)
            payload=payload,
            content_format=0        # text/plain
        )

    async def render_put(self, request):
        """Handle PUT requests to update configuration"""
        print(f'Received PUT: {request.payload}')

        # In real implementation, parse and apply config
        return Message(code=Code.CHANGED)  # 2.04 Changed

async def main():
    # Create CoAP server with resource tree
    root = resource.Site()

    # Add temperature resource at /temperature
    root.add_resource(
        ['temperature'],
        TemperatureResource()
    )

    # Start server on default CoAP port (5683)
    await Context.create_server_context(root)

    print("CoAP server started on port 5683")
    print("Resources: /temperature (GET, PUT)")

    # Keep server running
    await asyncio.get_running_loop().create_future()

if __name__ == "__main__":
    asyncio.run(main())

The server above registers /temperature only. The /config PUT and /readings POST clients below need matching server resource handlers before they can succeed. To receive Observe updates, make the temperature handler an ObservableResource and call updated_state() after a value changes; the plain Resource above does not register an observation.

Install and run:

pip install aiocoap
python coap_server.py

22.8.2 Adding Multiple Resources

The next implementation extends one server with two different resource contracts. ConfigResource supports GET for the current configuration and PUT for an idempotent update, returning Code.CHANGED only after decoded JSON has been applied. ReadingsResource is POST-only because each payload adds a reading rather than replacing the collection. As you inspect the code, keep routing, method semantics, Content-Format 50, validation, and response codes aligned; sharing a server process does not make the resources interchangeable.

class ConfigResource(resource.Resource):
    """Configuration resource with GET and PUT"""

    def __init__(self):
        super().__init__()
        self.config = {"interval": 60, "threshold": 25.0}

    async def render_get(self, request):
        import json
        payload = json.dumps(self.config).encode('utf-8')
        return Message(
            code=Code.CONTENT,
            payload=payload,
            content_format=50  # application/json
        )

    async def render_put(self, request):
        import json
        try:
            new_config = json.loads(request.payload.decode('utf-8'))
            self.config.update(new_config)
            print(f'Config updated: {self.config}')
            return Message(code=Code.CHANGED)
        except Exception as e:
            return Message(code=Code.BAD_REQUEST)

class ReadingsResource(resource.Resource):
    """POST-only resource to receive sensor readings"""

    async def render_post(self, request):
        import json
        try:
            reading = json.loads(request.payload.decode('utf-8'))
            print(f'New reading: {reading}')
            # Store reading in database...
            return Message(code=Code.CREATED)  # 2.01 Created
        except Exception:
            return Message(code=Code.BAD_REQUEST)  # 4.00 Bad Request

# In main():
root.add_resource(['config'], ConfigResource())
root.add_resource(['readings'], ReadingsResource())

With the server mapped, the client examples become trace recipes: request, response code, payload, and failure branch.

22.10.1 Basic GET Request

22.10.2 Step 2: Send GET and inspect the response

• In a second Python terminal, point the GET client below at the listening server and run it once.
• The executed localhost exchange returned client GET -> 2.05 Content payload=b'22.5' from a real aiocoap server and client.
• Compare the server token with the client’s request context and confirm the response payload decodes to 22.5.
• Record the path, response code, content format, token, and payload; a successful Python print alone does not prove a separate ESP32 implementation.
• If the server is absent, preserve the timeout or connection error instead of substituting the expected 2.05 line.

import asyncio
from aiocoap import *

async def get_temperature():
    """Fetch temperature from CoAP server"""

    # Create CoAP client protocol
    protocol = await Context.create_client_context()

    # Build GET request
    request = Message(
        code=Code.GET,
        uri='coap://localhost/temperature'
    )

    try:
        # Send request and wait for response
        response = await protocol.request(request).response

        print(f'Response Code: {response.code}')
        if response.code.is_successful():
            print(f'Temperature: {response.payload.decode("utf-8")}°C')
        else:
            print(f'GET failed: {response.code}')

    except Exception as e:
        print(f'Failed to fetch: {e}')

# Run client
asyncio.run(get_temperature())

22.10.3 PUT Request for Configuration

22.10.4 Step 3: Match the PUT path to a registered handler

• The client below targets /config; first inspect the server resource tree, which currently registers only /temperature.
• The local run sent PUT to /temperature and observed server PUT payload=b'23.5' followed by client PUT -> 2.04 Changed.
• A separate local GET /config returned 4.04 Not Found, confirming that the published /config example needs its own server handler.
• Add a /config handler in your lab copy, run the client, then read back the stored interval to prove the state actually changed.
• Record the failed and successful paths distinctly; a 2.04 from /temperature cannot be used as evidence for /config.

async def update_config():
    """Send PUT request to update configuration"""

    protocol = await Context.create_client_context()

    request = Message(
        code=Code.PUT,
        uri='coap://localhost/config',
        payload=b'{"interval": 30}'
    )

    response = await protocol.request(request).response
    print(f'Update result: {response.code}')

    if response.code.is_successful():
        print('Configuration updated successfully')
    else:
        print(f'Update failed: {response.code}')

asyncio.run(update_config())

22.10.5 POST Request to Send Data

22.10.6 Step 4: Register and verify the reading endpoint

• The POST client below sends JSON to /readings; inspect its application/json content format and encoded payload before sending.
• Against the chapter’s unextended server, the local aiocoap run returned client POST /readings -> 4.04 Not Found.
• Add a /readings POST handler to your lab server, validate the sensor ID and timestamp, and return 2.01 Created only after storing a reading.
• Match the sent sensor ID with a server-side stored record or receipt; a client-side “submitted” print is insufficient evidence of persistence.
• The endpoint extension was not run here, so 2.01 Created remains the expected result after the learner implements the handler.

import json

async def send_reading():
    """POST a sensor reading to the server"""

    protocol = await Context.create_client_context()

    reading = {
        "sensor_id": "temp-001",
        "temperature": 23.5,
        "humidity": 65.2,
        "timestamp": "2025-10-24T23:30:00Z"
    }

    request = Message(
        code=Code.POST,
        uri='coap://localhost/readings',
        payload=json.dumps(reading).encode('utf-8')
    )
    request.opt.content_format = 50  # application/json

    response = await protocol.request(request).response

    if response.code == Code.CREATED:
        print('Reading submitted successfully')
    else:
        print(f'Submission failed: {response.code}')

asyncio.run(send_reading())

22.10.7 Observe Pattern (Subscribe to Updates)

22.10.8 Step 5: Add a real observable resource before subscribing

• The plain TemperatureResource above does not implement Observe; change it to an ObservableResource in your lab copy.
• Call updated_state() after a reading changes, then run the Observe client below in a second terminal.
• Record the initial 2.05 response, each notification token, each message ID, and the changed payload value.
• Cancel the subscription and confirm the server stops notifications; a printed loop without exchanged CoAP packets is only a model.
• Observe was not run in this lane because the shown server lacks the required handler; no notification trace is claimed.

async def observe_temperature():
    """Subscribe to temperature updates using Observe"""

    protocol = await Context.create_client_context()

    request = Message(
        code=Code.GET,
        uri='coap://localhost/temperature',
        observe=0  # Register for notifications
    )

    request_handle = protocol.request(request)

    # Get initial response
    response = await request_handle.response
    print(f'Initial temperature: {response.payload.decode("utf-8")}C')

    # Wait for notifications (runs until cancelled)
    print('Waiting for updates...')
    async for response in request_handle.observation:
        print(f'Update: {response.payload.decode("utf-8")}C')
        # In real code, add break condition or timeout

asyncio.run(observe_temperature())

#include <WiFi.h>

// Simulated CoAP resource registry
struct CoapResource {
  const char* path;
  float value;
  bool observable;
  int observeCount;
};

CoapResource resources[] = {
  {"/temperature", 22.5, true, 0},
  {"/humidity", 65.0, true, 0},
  {"/config/interval", 60.0, false, 0},
  {"/led", 0.0, false, 0}
};
const int NUM_RESOURCES = 4;

// CoAP response codes (RFC 7252)
const char* COAP_205_CONTENT = "2.05 Content";
const char* COAP_204_CHANGED = "2.04 Changed";
const char* COAP_201_CREATED = "2.01 Created";
const char* COAP_404_NOT_FOUND = "4.04 Not Found";
const char* COAP_405_NOT_ALLOWED = "4.05 Method Not Allowed";

unsigned long lastObserve = 0;
int messageId = 1000;

void setup() {
  Serial.begin(115200);
  delay(1000);

  Serial.println("=== CoAP Resource Contract Simulation ===");
  Serial.println("Printing CoAP-style methods on ESP32; no UDP packets are sent.\n");

  // Show resource discovery (/.well-known/core)
  discoverResources();

  // Demonstrate GET requests
  Serial.println("\n--- GET Requests ---");
  coapGet("/temperature");
  coapGet("/humidity");
  coapGet("/config/interval");
  coapGet("/nonexistent");

  // Demonstrate PUT requests
  Serial.println("\n--- PUT Requests (Update Resources) ---");
  coapPut("/config/interval", 30.0);
  coapPut("/led", 1.0);
  coapGet("/config/interval");  // Verify change

  // Demonstrate POST (create reading)
  Serial.println("\n--- POST Request (Submit Reading) ---");
  coapPost("/readings", 23.7);

  // Demonstrate Observe pattern
  Serial.println("\n--- Observe Pattern (Subscribe to Updates) ---");
  Serial.println("Registering observer for /temperature...");
  Serial.println("MID=" + String(messageId++) + " Token=0xAB | Observe=0 (Register)");
  Serial.println("Response: " + String(COAP_205_CONTENT) + " | Observe=1\n");

  Serial.println("Sending notifications every 2 seconds...\n");
}

void loop() {
  // Simulate Observe notifications
  if (millis() - lastObserve > 2000) {
    lastObserve = millis();

    // Update sensor values with drift
    resources[0].value += random(-10, 11) * 0.1;
    resources[1].value += random(-5, 6) * 0.1;
    resources[0].observeCount++;

    Serial.printf("Observe #%d | MID=%d | /temperature = %.1f C\n",
                  resources[0].observeCount, messageId++,
                  resources[0].value);

    // Show CON vs NON comparison
    if (resources[0].observeCount % 5 == 0) {
      Serial.println("  ^ CON (Confirmable) - requires ACK");
      Serial.println("    Client ACK received (MID=" + String(messageId - 1) + ")");
    } else {
      Serial.println("  ^ NON (Non-confirmable) - no ACK needed");
    }

    // Show message size comparison
    if (resources[0].observeCount == 3) {
      Serial.println("\n--- Protocol Overhead Comparison ---");
      Serial.println("Illustrative GET /temperature exchange: CoAP 18B request + 11B response = 29B");
      Serial.println("Literal HTTP/1.1 exchange: 43B request + 42B response = 85B");
      Serial.printf("CoAP application bytes: %.0f%% fewer in this example\n\n",
                    (1.0 - 29.0 / 85.0) * 100);
    }

    if (resources[0].observeCount >= 10) {
      Serial.println("\nDeregistering observer (Observe=1)...");
      Serial.println("Observer removed. Server stops notifications.\n");
      Serial.println("=== CoAP Demo Complete ===");
      while (1) delay(1000);
    }
  }
}

void discoverResources() {
  Serial.println("GET /.well-known/core (Resource Discovery)");
  Serial.println("Response: " + String(COAP_205_CONTENT));
  Serial.println("Content-Format: application/link-format\n");
  for (int i = 0; i < NUM_RESOURCES; i++) {
    Serial.printf("  <%s>;rt=\"sensor\";if=\"core.s\"",
                  resources[i].path);
    if (resources[i].observable) Serial.print(";obs");
    Serial.println();
  }
}

CoapResource* findResource(const char* path) {
  for (int i = 0; i < NUM_RESOURCES; i++) {
    if (strcmp(resources[i].path, path) == 0) return &resources[i];
  }
  return NULL;
}

void coapGet(const char* path) {
  Serial.printf("GET %s | MID=%d\n", path, messageId++);
  CoapResource* res = findResource(path);
  if (res) {
    Serial.printf("  Response: %s | %.1f\n", COAP_205_CONTENT, res->value);
  } else {
    Serial.printf("  Response: %s\n", COAP_404_NOT_FOUND);
  }
}

void coapPut(const char* path, float value) {
  Serial.printf("PUT %s | MID=%d | Payload: %.1f\n", path, messageId++, value);
  CoapResource* res = findResource(path);
  if (res) {
    res->value = value;
    Serial.printf("  Response: %s | Updated to %.1f\n", COAP_204_CHANGED, value);
  } else {
    Serial.printf("  Response: %s\n", COAP_404_NOT_FOUND);
  }
}

void coapPost(const char* path, float value) {
  Serial.printf("POST %s | MID=%d | Payload: {temp: %.1f}\n",
                path, messageId++, value);
  Serial.printf("  Response: %s | Location: /readings/1\n", COAP_201_CREATED);
}

22.11.1 Step 7: Verify the ESP32 packet path on your own hardware

• On your own ESP32 and Wi-Fi network, set the server address and port in the sketch, then start a real CoAP server with the matching resources.
• In the ESP32 serial monitor, record the GET, PUT, and POST send lines and the callback’s response code and payload.
• Capture UDP port 5683 in Wireshark and match the request token, message ID, resource path, and reply to the serial record.
• Keep /config and /readings disabled until the Python server has matching handlers, or record their 4.04 responses as expected failures.
• No ESP32, Wi-Fi packet capture, or physical radio path was run here; the localhost aiocoap exchange is the only real CoAP network result in this lane.

#include <WiFi.h>
#include <coap-simple.h>

// WiFi credentials
const char* ssid = "YourWiFi";
const char* password = "YourPassword";

// CoAP client instance
Coap coap;

// Server details
IPAddress serverIP(192, 168, 1, 100);
int serverPort = 5683;

// Callback for CoAP responses
void callback_response(CoapPacket &packet, IPAddress ip, int port) {
  // Extract payload
  char payload[packet.payloadlen + 1];
  memcpy(payload, packet.payload, packet.payloadlen);
  payload[packet.payloadlen] = '\0';

  Serial.print("Response from ");
  Serial.print(ip);
  Serial.print(": ");
  Serial.println(payload);

  // Check response code
  Serial.print("Code: ");
  Serial.print(packet.code >> 5);  // Class (2=Success, 4=Client Error, 5=Server Error)
  Serial.print(".");
  Serial.println(packet.code & 0x1F);  // Detail
}

void setup() {
  Serial.begin(115200);

  // Connect to WiFi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  Serial.println("\nWiFi connected");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());

  // Register response callback
  coap.response(callback_response);

  // Start CoAP client
  coap.start();
}

void loop() {
  // Send GET request every 10 seconds
  static unsigned long lastRequest = 0;

  if (millis() - lastRequest > 10000) {
    int msgid = coap.get(serverIP, serverPort, "temperature");
    Serial.print("GET /temperature sent, MID: ");
    Serial.println(msgid);
    lastRequest = millis();
  }

  // Process incoming responses
  coap.loop();
}

22.11.2 ESP32 PUT Request Example

void sendConfig() {
  // Build JSON payload
  char payload[64];
  snprintf(payload, sizeof(payload), "{\"interval\": %d}", 30);

  // Send PUT request
  int msgid = coap.put(
    serverIP,
    serverPort,
    "config",
    payload,
    strlen(payload)
  );

  Serial.print("PUT /config sent, MID: ");
  Serial.println(msgid);
}

22.11.3 ESP32 POST Request Example

void sendReading() {
  // Read sensor (simulated)
  float temperature = 22.5 + (random(-10, 10) / 10.0);
  float humidity = 60.0 + (random(-50, 50) / 10.0);

  // Build JSON payload
  char payload[128];
  snprintf(payload, sizeof(payload),
    "{\"temp\": %.1f, \"hum\": %.1f}",
    temperature, humidity);

  // Send POST request
  int msgid = coap.post(
    serverIP,
    serverPort,
    "readings",
    payload,
    strlen(payload)
  );

  Serial.print("POST /readings sent: ");
  Serial.println(payload);
}