Meatloaf Networking

Meatloaf Networking — Language-Agnostic Reference

Meatloaf is an ESP32 firmware (project: idolpx/meatloaf) that plugs into a Commodore 64's IEC serial bus and emulates one or more virtual disk drives. It exposes a WiFi TCP/IP stack to the C64 by acting as a "device" on the bus. From a programmer's point of view you are not driving a network interface — you are driving an IEC device that happens to accept URLs as filenames.

The interesting part of Meatloaf is its full-mode HTTP client: opening a channel with secondary address 2 puts the device into a mode where each line you write to the channel is a command (m get, h content-type: application/json, b {…}, s, …) and each byte you read back is part of the HTTP response. This is what lets a C64 — or any other client — make arbitrary HTTP requests with custom headers and bodies, and parse the response.

This document describes the protocol, not any one language's API for it. BASIC, C, assembly, and host-side tooling all reduce to the same primitives: open a channel, write command lines, read response bytes, watch the EOI/error flags.

The mental model

Think of Meatloaf as a tiny HTTP server on the bus that takes orders line by line and hands you bytes back. There is no library to link. There is no driver to install. There is no "Meatloaf API". The whole interface is six bytes of IEC protocol and a CR-terminated command language.

   Client (your code)                    Meatloaf (ESP32)
   ────────────────                      ────────────────
   OPEN channel, sec=2, name="URL"  ──►  parses URL, opens TCP
   WRITE "m get" + CR/LF              ──►  records method
   WRITE "h accept: */*" + CR/LF      ──►  records header
   WRITE "s" + CR/LF                  ──►  sends request, reads response
   WRITE "status" + CR/LF             ──►  positions read cursor
   READ  bytes until EOI               ◄──  "200\r"
   WRITE "j /path" + CR/LF            ──►  extracts JSON Pointer
   READ  bytes until EOI               ◄──  extracted value (PETSCII)
   CLOSE                              ──►  resets

That's the whole thing. The rest of this document fills in the details.

IEC bus model (the layer below)

The IEC serial bus is the 6-pin cable that connects a C64 to disk drives, printers, and (in our case) Meatloaf. You don't need to know the bus in depth to use the protocol, but knowing three things saves hours of confusion:

• Device numbers: IEC supports up to 30 logical devices (numbers 4–30 are valid; 8–15 are conventional for disk drives). Meatloaf picks its own device number at boot — you must know which one it claimed (the C64 stores the last-used device in a variable and you can LOAD"$",8 to list its catalog; or read Meatloaf's boot banner over serial).
• Secondary addresses: a "channel" is identified by the pair (device, secondary_address). Secondary address 0 and 1 are the standard LOAD/SAVE channels. Secondary address 2 is the magic value that puts Meatloaf into full HTTP mode. (Other secondary addresses either open a disk-like file or are unused.)
• Three things travel on the bus: ATN (attention), data characters, and an end-of-data marker called EOI. EOI is how the device tells you "no more bytes" — read it as a single boolean flag, not a character.

The exact wire protocol (ATN low, listen/talk bytes, turn-around, acknowledgement) is handled by your runtime's IEC kernal calls. From your code you only ever call:

Status flags (consolidated, regardless of platform):

Every language surfaces these differently (BASIC: ST with bit masks 64 and 128; C: a cbm_errno_t; assembly: CIA interrupt status). The semantics are the same. From here on, this document talks about the protocol in those semantic terms — your language will give you specific constants.

The Meatloaf full-mode command language

Once a channel is open with secondary address 2, every byte you write to the channel is part of a line. A line is terminated by any of CR (0x0D), LF (0x0A), or CRLF — Meatloaf treats all three as command terminators. Each complete line is a command. Commands are case-insensitive at the firmware level; always use lowercase for consistency with existing clients and the BASIC convention.

* delete is not currently supported by MeatHttpClient (see Limitations).

How s works

s is the only command that talks to the network. Everything else is just queueing state on the device. After s returns, the full HTTP response (status line, all headers, all body bytes) is buffered in Meatloaf and you can read it back through the channel by issuing status, r-h, or r-b first, then reading until EOI.

There is no streaming. The whole response fits in Meatloaf's RAM (typically 8 KB+ depending on ESP32 variant) before you can read any of it. If the server sends more than Meatloaf can buffer, the request will hang or fail.

How j works

j <pointer> is a convenience for clients that don't want to parse JSON themselves. It runs an RFC 6901 JSON Pointer (see json_pointer.md for the full syntax reference) (e.g. /choices/0/message/content) against the captured response body and queues just the extracted value (or null if the pointer doesn't match) for read-back, the same way r-b does for the full body.

j is the recommended way to read JSON responses. Real clients (e.g. c64u_radar.c) prefer j over r-b because:

• the C64 has no JSON parser in BASIC and a tiny one in cc65;
• j skips parsing the surrounding object/array structure;
• each j query can be issued independently on the same channel without re-sending the request;
• the result is already PETSCII-transcoded for display.

If the response isn't valid JSON, or the pointer doesn't match, the j path returns -99 and a short error string in the status view (e.g. JSON parse error, JSON pointer not found).

Reading the response

Reading is a three-step dance every time:

1. Issue a positioning command (status, r-h, or r-b).
2. Read bytes one at a time until EOI.
3. The end-of-chunk is signaled by the EOI flag on the last byte, not by a special character. (The HTTP body itself may or may not have a trailing newline — Meatloaf passes server bytes through unchanged.)

The status and r-h views are line-oriented: each line ends with CR (0x0D). Read until you see CR, then start the next line. For r-h, a CR followed immediately by EOI (or by an empty line followed by EOI) marks the end of the headers section.

r-b is byte-oriented: no special end marker inside the body, just EOI when Meatloaf has handed you the last byte.

Error and status mapping

The -1 and -2 codes come from HTTPRequestContext::errorToIecStatus in Meatloaf's http.cpp; the -99 is a separate code that the JSON Pointer path returns when parsing or pointer resolution fails. Any negative status value should be treated as "transport- or parse-level error" and the connection should be closed and retried by the caller.

Encoding note (read this — it differs by command)

The r-h and r-b paths pass server bytes through unchanged (useful for byte comparisons and JSON parsers). The j path converts the extracted JSON value from ASCII/UTF-8 to PETSCII before handing it to the client, because that's what the C64 display expects. Don't try to feed j output into a JSON parser on the C64 — it's already transcoded.

For the write path (sending headers and bodies): command characters are decoded from PETSCII to UTF-8 inside the firmware before being put on the wire, so PETSCII uppercase letters from a BASIC program end up as ASCII lowercase in the actual HTTP header. The C64 doesn't need to know this is happening.

Worked examples

C (cc65)

cc65 exposes the IEC bus through <cbm.h> with four functions: cbm_open, cbm_close, cbm_write, cbm_read. The secondary_address argument selects the protocol mode — 2 puts Meatloaf into full HTTP mode, anything else opens a disk-like file emulation. The example below is condensed from c64u_radar.c (an ADS-B radar client that talks to adsb.fi over HTTPS) and shows the full GET/JSON Pointer cycle.

#include <stdio.h>
#include <string.h>
#include <cbm.h>

#define CH   2        /* Meatloaf logical channel          */
#define DEV  8        /* Meatloaf IEC device number        */
#define SA   2        /* secondary address: full HTTP mode */

static unsigned char ml_read_val(unsigned char ch, char* buf,
                                 unsigned char maxlen)
{
    /* Read bytes one at a time, stopping at CR/LF or EOI.
     * cbm_read() returns 0 on EOI; on success it returns 1. */
    unsigned char i = 0;
    while (i < maxlen - 1) {
        if (cbm_read(ch, (unsigned char*)(buf + i), 1) == 0) break;
        if (buf[i] == '\r' || buf[i] == '\n') break;
        ++i;
    }
    buf[i] = 0;
    return i > 0;
}

static unsigned char j_str(unsigned char ch, const char* pointer,
                           char* buf, unsigned char maxlen)
{
    cbm_write(ch, "j ", 2);
    cbm_write(ch, pointer, (unsigned char)strlen(pointer));
    cbm_write(ch, "\r\n", 2);
    return ml_read_val(ch, buf, maxlen);
}

void fetch(const char* url) {
    char val[36];
    int http_status;

    /* Open a URL on Meatloaf.  cbm_open does the IEC OPEN for us;
     * no manual secondary-address marshalling. */
    if (cbm_open(CH, DEV, SA, url) != 0) return;

    /* Queue the GET request.  Any of \r, \n, or \r\n terminates a
     * command line — \r\n is conventional and matches what
     * Meatloaf's test suite sends. */
    cbm_write(CH, "h user-agent: my-client/1.0\r\n", 28);
    cbm_write(CH, "m get\r\n", 7);
    cbm_write(CH, "s\r\n", 3);

    /* Read the HTTP status. */
    cbm_write(CH, "status\r\n", 8);
    if (!ml_read_val(CH, val, sizeof val)) goto done;
    http_status = atoi(val);
    if (http_status != 200) goto done;

    /* Pull a field via JSON Pointer.  The result is PETSCII-
     * converted by the firmware, so the bytes in `val` are
     * already screen-ready. */
    if (!j_str(CH, "/ac/0/flight", val, sizeof val)) goto done;
    printf("flight=%s\n", val);

done:
    cbm_close(CH);
}

A few things to note from the real code:

• cbm_read returns 0 on EOI, not a flag you have to mask. That makes the read loop straightforward.
• There's no c between requests in the radar client. The pattern is: open channel → do one full request cycle → close. Repeated fetches open a new channel each time, which is cheap.
• The j path is preferred over r-b because the C64 has no JSON parser and the field-extraction cost of j is much lower than reading the whole body and scanning for quotes.
• Body data is PETSCII on the j path but raw on r-b. The c64u_radar.c code only uses j, so it never deals with the raw case. If you must use r-b, allocate buffers for raw bytes and don't print them directly to screen without a PETSCII conversion.

cc65 character translation (PETSCII gotcha)

cc65 runs every string and character literal through an ASCII/ISO-8859-1 → PETSCII translation table when targeting Commodore machines. This is normally convenient — you write C source in ASCII and PETSCII-aware screen output "just works" — but several characters used in networking and JSON get mangled in ways that produce wrong bytes on the wire or wrong glyphs on screen.

Full translation table

This is the default mapping (ISO-8859-1 input → PETSCII output):