Skip to content

NETWORKING.md

Latest commit

 

History

History
325 lines (244 loc) · 12.7 KB

NETWORKING.md

File metadata and controls

325 lines (244 loc) · 12.7 KB
Raw

BMC64 Networking

This document describes the networking support currently implemented in BMC64. Networks is available for C64 and C128 machines. C64 has been tested with BBS access and C64 OS network enabled applications and C128 has been tested with BBS.

What It Does

BMC64 runs without Linux. The Raspberry Pi networking stack is initialized at startup and is used by a software modem connected to VICE's ACIA1 interface. The emulated C64 or C128 program sees a SwiftLink/Turbo232-compatible ACIA at $DE00 by default. The BMC modem translates modem commands into outbound TCP connections.

Current behavior:

  • Networking is available from the Network menu on C64 and C128.
  • The choices are Off, Ethernet, and WiFi.
  • Modem Address selects $DE00 (default) or alternatively $D700, $DF00, or $DF80.
    • $D700 is recommended if you are using an IDE64 and REU at the same time.
  • Ethernet uses the Raspberry Pi's onboard Ethernet controller when present.
  • Wi-Fi uses the Raspberry Pi's onboard WLAN controller when present.
  • The modem resolves DNS names and opens TCP connections.
  • The default TCP port is 23; a different port can be supplied in the dial string.
  • Basic Telnet negotiation is handled for BBS-style connections. Telnet control bytes are kept out of the data delivered to the C64 terminal.
  • C64 OS CNP traffic on port 6400 is binary-transparent. Every byte, including 0xff, reaches C64 OS unchanged.
  • The connection is outbound only. BMC64 does not listen for incoming modem calls or provide a BBS server.

This is Telnet-style, unencrypted TCP. It does not provide TLS, SSH, VPN, or HTTP client behavior.

DO NOT use it for credentials that must be protected.

Warning

The emulated SwiftLink modem occupies I/O space that some cartridges also use (for example REU, IDE64, GeoRAM, EasyFlash, MagicDisk or other $DE00/$DF00 devices). If networking is enabled at the same time as a conflicting cartridge you may see crashes or a non-responsive modem. Try a different Modem Address, or set Network Device to Off when you are not using networking.

Requirements

Wi-Fi requires Raspberry Pi firmware to be present in the /firmware directory at the root of the SD card. Follow the build instructions in BUILDING.md and use build_sdcard.sh to generate an SD-card image with the required firmware included.

To install the Wi-Fi firmware manually, build it from the repository root:

cd third_party/circle-stdlib/libs/circle/addon/wlan/firmware
make firmware

Then copy every generated file from that directory to /firmware on the SD card.

Enable Ethernet

  1. Connect the Raspberry Pi to the network with Ethernet.
  2. Boot BMC64 and open Network.
  3. Set Network Device to Ethernet.
  4. Save the setting and reboot when prompted.
  5. Open Network again and check IP Address.

The Ethernet choice is disabled when the selected Raspberry Pi model does not have onboard Ethernet. The IP address is populated when the Network menu is opened and the network stack has a running address.

Enable Wi-Fi

Wi-Fi requires a Raspberry Pi model with onboard WLAN and the required Wi-Fi firmware on the SD card.

Warning

Typing in the SSID and password in the fields in the BMC64 menu currently ONLY support letters and numbers. If you have special characters in your Wi-Fi SSID or password you need to enter them manually into wpa_supplicant.conf, see below.

Configure from the menu

  1. Open Network and set Network Device to WiFi.
  2. Accept the reboot prompt, or save the settings and reboot.
  3. After reboot, open Network -> WiFi Settings.
  4. Use the Wi-Fi scan to select an access point when scanning is available.
  5. Select the Modem Address desired.
  6. Select WPA-PSK or None as appropriate.
  7. Set the two-letter Wi-Fi country code.
  8. Choose Enter Password & Reboot, enter the WPA password, and select Save & Reboot.
  9. After reboot, open Network and verify the assigned IP Address.

Selecting Wi-Fi makes the Wi-Fi stack available at boot. It may take a 5-20 seconds after boot to connect to an access point depending if it needs to retry.

Configure the file manually

The configuration file is stored at the root of the SD-card volume as wpa_supplicant.conf. The repository includes an example at sdcard/wpa_supplicant.conf.example:

country=US

network={
    ssid="replace-with-network-name"
    psk="replace-with-network-password"
    key_mgmt=WPA-PSK
}

For an open network, use:

country=US

network={
    ssid="replace-with-network-name"
    key_mgmt=NONE
}

After changing the file, reboot BMC64. If Wi-Fi was not already selected, set Network Device to WiFi and reboot when prompted.

Web UI

BMC64 can serve a small status / reboot / file-management web page over the local network on C64 and C128. It is off by default and can be protected with an optional PIN. Enable it in Network -> Web UI Settings and open http://<bmc64-ip>/.

See WEBUI.md for the full description, security notes, and how to develop it locally.

BMC Modem Commands

The modem is attached to ACIA1. Commands are terminated with Return. The implemented command set is:

Command Result
AT Returns OK.
ATI / ATI<n> Returns the modem identification and OK.
ATI3 Returns the SSID most recently supplied through ATW, then OK.
ATE0 / ATE1 Disable or enable command echo.
ATQ0 / ATQ1 Enable or suppress result codes.
ATV0 / ATV1 Select numeric or text result codes.
ATR0 / ATR1 Select Return-only or CR/LF result-code termination.
ATF0 through ATF3 Accepted for ZiModem compatibility.
ATB<n> / ATX<n> Accepted; serial rate is controlled by the ACIA configuration.
AT&P<n>, AT&F<n>, AT&K<n>, AT&L<n>, AT&W<n> Accepted as ZiModem-compatible no-ops.
ATW"ssid,password" Records an SSID for ATI3; it does not change the Pi's Wi-Fi configuration.
ATC Reports whether BMC64's host network is running.
ATC... Resolve a host and open TCP while remaining in command mode.
ATZ Reset the modem state.
ATD... Resolve a host and open TCP data mode. ATDT, ATDP, and quoted targets are accepted.
ATO Return to data mode when a socket is still connected.
+++ Leave data mode after the one-second escape guard interval.
ATH / ATH0 Hang up the current connection.
AT+TRACE, AT+TRACECLEAR Read or clear the last 128 serial-backend bytes for diagnostics.
AT+ACIATRACE, AT+ACIATRACECLEAR Read or clear the last 128 SwiftLink data-register writes for diagnostics.

Dial targets may be hostnames or IPv4 addresses. The port is optional:

ATDTbbs.example.org
ATDTbbs.example.org:2323
ATDT192.168.1.50:6502

A successful connection returns CONNECT. DNS failure, an unavailable network, or a refused TCP connection returns NO CARRIER.

TCP is independent of a physical serial device, but the emulated ACIA still paces bytes at the speed selected by the terminal program or C64 OS driver. Set the desired rate in the C64 client; for C64 OS, set both baud fields to the same value. 38400 has been validated with CNP transfers.

Using a BBS

C64

CCGMS Ultimate on CSDb is a C64 BBS terminal program released by Alwyz in 2019. Transfer its disk image or program to the BMC64 SD card and load it on the C64 using the normal BMC64 disk or Autostart workflow.

The current BMC64 changelog specifically calls out this setup:

  1. Enable Ethernet or Wi-Fi and reboot BMC64.
  2. Start CCGMS Ultimate.
  3. In CCGMS, select the Swift/DE or appropriate modem.
    • D7, DE or DF should match the Modem address selected.
  4. Use CCGMS's autodialer/connection screen with the BBS hostname or IP address and TCP port.
  5. If entering commands directly in the terminal, use the BMC modem syntax, for example ATDTbbs.example.org:23, followed by Return.
  6. Wait for CONNECT, then follow the BBS login prompts.

Most traditional Internet BBSes use Telnet on port 23, but some use another port. Use the port published by the BBS operator. The BMC modem accepts both a hostname and an IPv4 address, so either form can be entered in CCGMS.

For further details on CCGMS Ultimate refer to the CSDb release page.

C128

DesTerm 128 V3.02 on CSDb has been tested with the BMC64 modem in C128 mode. Transfer the DesTerm program or disk image to the C128 directory on the BMC64 SD card, then load it using the normal BMC64 disk or Autostart workflow.

Note: DesTerm 128 uses the C128 80-column display.

  1. Enable Ethernet or Wi-Fi in BMC64 and reboot it if prompted.
  2. In BMC64's Network menu, note the selected Modem Address. $DE00 is the default.
  3. DesTerm should automatically detect the modem and address.
  4. Use DesTerm's dialer to enter the BBS hostname or IPv4 address and its TCP port. Alternatively, enter a dial command in the terminal, for example:
ATDTbbs.example.org:23
  1. Wait for CONNECT, then log in to the BBS.
  2. Select the character set supported by the BBS if prompted. DOS CP 437 worked well with the tested BBS.
  3. Use the port published by the BBS operator when it differs from the default Telnet port 23.

To disconnect from a terminal session, wait at least one second, enter +++, wait at least one second for OK, then enter ATH.

Note: DesTerm 128 does not use PETSCII. Choose a character set supported by the BBS.

Using C64 OS Networking

C64 OS provides SwiftLink drivers for the modem addresses configured in the BMC64 Network menu.

Modem address $D700 with the sld7.zi driver is recommended when using an IDE64 C64 OS image with an REU enabled to avoid address collisions.

Modem address $DE00 with the slde.zi driver is recommended when using a CMD-HD C64 OS image with an REU enabled to avoid address collisions.

The driver sends a ZiModem-compatible initialization command, uses ATW and ATI3 to identify the host connection, and dials the CNP service using a quoted ATD target.

Networking in C64 OS uses C64 Network Protocol (CNP), which requires a CNP server account. For full information, read the C64 OS Networking Guide.

Quick start for BMC64:

  1. Configure Ethernet or Wi-Fi in BMC64 and confirm that Network Status shows as connected.
    • Note: The C64 OS Wi-Fi fields do not configure the Raspberry Pi Wi-Fi.
  2. In C64 OS, open Settings, then Network. On the Drvr tab, select the driver matching BMC64's Modem Address: sld7.zi for $D700, slde.zi for $DE00, or sldf.zi for $DF00.
  3. Set both Ini.Baud and Max.Baud to 38400, save the settings, and run Test. It must report Pass before attempting CNP.
  4. On the WiFi tab, enter non-empty values and use Join so C64 OS can complete its driver workflow. BMC64 leaves the host network unchanged.
  5. On the CNP tab, configure services.c64os.com as the host and 6400 as the port, then supply your C64 OS service credentials and click Start.
  6. Open the C64 OS Wikipedia application, run a search, and select several content links. Each item should download and display; this exercises CNP's binary payload path rather than just the initial connection.
  7. Click Stop when finished. C64 OS should leave its active yellow state; BMC64 closes the TCP connection when the driver lowers DTR. A remote CNP disconnect produces the same state transition through the SwiftLink NMI.

Testing and Debugging

Modem Transport Probe

Before troubleshooting a live BBS, the repository includes a TCP transport probe. It was originally used to diagnose TCP stalling issues.

Run it on another computer on the same LAN as BMC64:

hostname -I
python3 tools/modem_transport_probe.py --host <computer-lan-ip>

The probe listens on TCP port 6502. From CCGMS, dial:

ATDT<computer-lan-ip>:6502

The probe exercises receive and transmit data and keeps the connection open. For a pager-style test that waits for Space, run:

python3 tools/modem_transport_probe.py \
    --host <computer-lan-ip> --require-space

For the fragmented receive test used during modem transport debugging, run:

python3 tools/modem_transport_probe.py \
    --host <computer-lan-ip> --fragmented-burst --tcp-nodelay

See tools/TRANSPORT_PROBE.md for the expected probe output and the interpretation of unacked and retrans counters.

Modem Command Probe

This probe is used to test the connection to a CNP server from within C64 OS.

Run it on another computer on the same LAN as BMC64:

For a local, credential-free driver and DTR test before using CNP, follow tools/MODEM_COMMAND_PROBE.md.