Debugging

lwIP-CE provides complementary tools for diagnosing problems.

  • [Recommended] The toggleable, user-controlled PCAP and Logging interfaces.

  • A live event callback function and traceback system.

Neither requires a debugger or a serial console — both work on real hardware.


Packet Capture and Logging interface

If you are on v3.0.0-rc2 or later you can run lwIP directly from the [apps] menu and scroll down to the Diagnostics group. From there, you can toggle packet captures and logging as well as feature-specific settings: packet capture size limit, log verbosity, max number of log slots (log slots are capped to 16 KiB, 9 slots max).

The project maintainer’s website hosts a Bug Reporting Assistant designed for allowing a user to file a bug. This utility automatically files a GitHub issue on your behalf while also allowing you to submit lwIP-CE-serialized packet captures and logfiles either via upload or via WebUSB directly from your connected calculator. The captures are decoded: packet captures into Wireshark-compatible pcap files; the logs into log files. Because these files may contain sensitive information (IP addresses, hostnames, packet contents), they are sent into a dev-only Discord channel rather than filed with your GitHub issue. This will help us with debugging any issues that may arise.

This is the recommended way to diagnose lwIP-CE problems because collection is reliable and remains under the end user’s control. Applications can also consume the event and traceback interfaces described below.

Unified event callback

All modules (USB driver, TLS, allocator, socket layer, WebSocket) route their events through a single callback registered with lwip_set_event_cb():

void lwip_set_event_cb(lwip_event_fn event_fn);

Pass NULL to disable (callback is disabled by default). The callback signature is:

typedef void (*lwip_event_fn)(const struct lwip_event *ev);

struct lwip_event has two fixed fields and a union:

struct lwip_event {
    uint8_t module;   /* lwip_debug_module_t — which component fired */
    uint8_t kind;     /* lwip_event_kind_t   — what kind of event    */
    union { ... } data;
};

Module values (ev->module):

Constant

Component

LWIP_DBG_MOD_LWIP

Socket/connection layer, netif, dispatch

LWIP_DBG_MOD_USB

USB Ethernet driver

LWIP_DBG_MOD_MEM

Custom allocator

LWIP_DBG_MOD_TLS

TLS handshake, record layer, crypto

LWIP_DBG_MOD_WS

WebSocket framing layer

Call lwip_debug_module_name(ev->module) for a human-readable label (e.g. "tls").

Event kinds (ev->kind):

Kind

Meaning and data field used

LWIP_EV_INFO

Normal progress milestone. data.msg is a literal string.

LWIP_EV_DEBUG

Trace point. Self-throttled: only fires when the {file, line} changes from the previous DEBUG emit. data.code.loc encodes the location; data.code.extra is 0.

LWIP_EV_WARN

The stack noticed a problem but chose to proceed (for example, an unsupported certificate link type that was tolerated). data.code carries the location and an optional extra value.

LWIP_EV_ERROR

Hard failure. data.code carries the location and optional extra.

LWIP_EV_STATE_CHG

A meaningful state transition. data.state.owner is the object (e.g. a socket pointer); data.state.change_event is a lwip_state_change_t value.

LWIP_EV_IO_FILE

AppVar or Flash read/write. data.file.dir (LWIP_IO_READ / LWIP_IO_WRITE), data.file.name, data.file.bytes.

LWIP_EV_IO_ETH

Network bytes received or sent. data.eth.dir (LWIP_IO_RX / LWIP_IO_TX), data.eth.bytes.

LWIP_EV_POWER

USB or battery power state change. data.power.subtype (lwip_power_event_t), data.power.charging.

State change values for LWIP_EV_STATE_CHG:

Constant

Meaning

LWIP_STATE_LINK_UP / LWIP_STATE_LINK_DOWN

Ethernet link state changed.

LWIP_STATE_IP_ACQUIRED / LWIP_STATE_IP_LOST

DHCP address assigned or lost.

LWIP_STATE_CONN_CONNECTING

Connection attempt in progress.

LWIP_STATE_CONN_ESTABLISHED

Connection is up and ready for I/O.

LWIP_STATE_CONN_CLOSED

Connection closed cleanly.

LWIP_STATE_CONN_FAILED

Connection failed (error or timeout).

LWIP_STATE_TLS_HANDSHAKE_BEGIN

TLS handshake started.

LWIP_STATE_TLS_HANDSHAKE_DONE

TLS handshake succeeded.

LWIP_STATE_TLS_HANDSHAKE_FAILED

TLS handshake failed.

Call lwip_debug_state_change_name(ev->data.state.change_event) for a human-readable label (e.g. "conn_established").

Decoding a code event location:

ERROR, WARN, and DEBUG events encode {file_id, line} into data.code.loc:

uint8_t  file_id = LWIP_EVENT_CODE_FILE(ev->data.code.loc);
uint32_t line    = LWIP_EVENT_CODE_LINE(ev->data.code.loc);
uint16_t extra   = ev->data.code.extra;   /* 0 for bare ERROR()/WARN() */

/* Human-readable file name: */
const char *filename = lwip_debug_file_name(file_id);  /* e.g. "handshake.c" */

Minimal event callback example:

#include <lwip.h>
#include <ti/screen.h>
#include <stdio.h>

static void on_event(const struct lwip_event *ev)
{
    char buf[80];
    switch (ev->kind) {
    case LWIP_EV_INFO:
        snprintf(buf, sizeof(buf), "[info] %s\n", ev->data.msg);
        break;
    case LWIP_EV_WARN:
        snprintf(buf, sizeof(buf), "[warn] %s:%lu extra=%u\n",
                 lwip_debug_file_name(LWIP_EVENT_CODE_FILE(ev->data.code.loc)),
                 LWIP_EVENT_CODE_LINE(ev->data.code.loc),
                 ev->data.code.extra);
        break;
    case LWIP_EV_ERROR:
        snprintf(buf, sizeof(buf), "[error] %s:%lu extra=%u\n",
                 lwip_debug_file_name(LWIP_EVENT_CODE_FILE(ev->data.code.loc)),
                 LWIP_EVENT_CODE_LINE(ev->data.code.loc),
                 ev->data.code.extra);
        break;
    case LWIP_EV_STATE_CHG:
        snprintf(buf, sizeof(buf), "[state] %s\n",
                 lwip_debug_state_change_name(ev->data.state.change_event));
        break;
    default:
        return;
    }
    os_PutStrFull(buf);
}

int main(void)
{
    if (!lwip_start()) return 1;
    lwip_set_event_cb(on_event);
    /* ... */
}

Traceback

The event callback fires in real time. If a failure happens mid-handshake, you may not have a screen up yet, or the failure may be buried inside a chain of callbacks. The traceback buffer captures the most recent WARN and ERROR events (and socket-layer errors) automatically, in newest-first order. Read it any time after a failure:

const struct lwip_traceback_entry *lwip_get_traceback(uint8_t *count);

count is filled with the number of entries. The returned pointer is owned by lwIP and is valid until the next call to lwip_get_traceback() or until a new entry is pushed into the buffer. Copy what you need before calling anything else.

struct lwip_traceback_entry fields:

Field

Type

Meaning

module

uint8_t

lwip_debug_module_t — which component raised the event.

kind

uint8_t

lwip_event_kind_t — LWIP_EV_WARN or LWIP_EV_ERROR for code entries; other values for socket-wrapper entries.

file

uint8_t

lwip_debug_file_id_t — source file. Pass to lwip_debug_file_name() to get the filename string. Zero for socket-wrapper entries (the causal ERROR is expected to precede them).

line

uint32_t

Source line number. Zero for socket-wrapper entries.

extra

uint16_t

Optional extra code from ERROR_CODE() / WARN_CODE(); 0 for bare ERROR() / WARN().

component

uint16_t

lwip_socket_error_component_t for socket-wrapper entries; 0 otherwise.

operation

uint16_t

lwip_socket_error_operation_t for socket-wrapper entries; 0 otherwise.

raw_error

int

Raw err_t or module-specific code for socket-wrapper entries; 0 otherwise.

mapped_error

uint16_t

lwip_error_t for socket-wrapper entries; 0 otherwise.

status

uint16_t

lwip_status_t for socket-wrapper entries; 0 otherwise.

Traceback walkthrough example:

uint8_t count;
const struct lwip_traceback_entry *tb = lwip_get_traceback(&count);

for (uint8_t i = 0; i < count; i++) {
    const struct lwip_traceback_entry *e = &tb[i];
    if (e->file) {
        /* Code-level WARN or ERROR */
        printf("[%s] %s:%lu",
               lwip_debug_module_name(e->module),
               lwip_debug_file_name(e->file),
               e->line);
        if (e->extra)
            printf(" extra=0x%04x", e->extra);
        printf("\n");
    } else {
        /* Socket-wrapper error entry */
        printf("[socket] component=%u op=%u raw=%d mapped=%u status=%u\n",
               e->component, e->operation,
               e->raw_error, e->mapped_error, e->status);
    }
}

Note

DEBUG events do not occupy traceback slots — they are callback-only. Only WARN, ERROR, and socket-wrapper errors are captured.