C64 OS Networking Guide

Introduction: Part I

Part I of the C64 OS Networking Guide focuses on what you need to know to get online with your C64 and with C64 OS. This includes, picking hardware and various hardware considerations, using the Network Utility to select and set up the network hardware driver, connect to a Wifi hotspot (if necessary), and how to configure your CNP server credentials.

Part I also discusses what you can do with C64 OS networking, and practical considerations for sharing your network hardware between C64 OS and non-C64-OS software, fast app switching, etc.

Part II of this guide is more philosophical and more technical. It describes how the Commodore Network Protocol works and what sorts of networking Applications it can enable.

The future belongs to those who believe in the beauty of their dreams. Eleanor Roosevelt .

---

Part I: Getting Online

Networking in C64 OS is more similar to networking in any modern operating system than it is to the way in which a traditional Commodore 64 program talks directly to a modem.

C64 OS itself goes online and provides a networking API to Applications and Utilities so that they can share the network hardware. This becomes particularly useful when using an REU and Fast App Switching. Although open Applications are frozen in the background, you can quickly switch between open Apps and each can establish connections to the internet without interfering with each other and without regard to the technical specifications of the underlying hardware.

Network Overview

A network stack is called a stack because there are many parts arranged in layers that are involved in the process of getting online and using network resources. The following is a summary of that stack. It isn't necessary to understand how these layers work, but it's useful (and perhaps even interesting) to know what's involved.

• Network Accessing Applications
  (e.g., Wikipedia, MoonPhase, etc.)
• Network Configuration Utility
  (//os/utilities/:Network)
• Network Libraries
  (//os/library/:cnp.lib, network.lib)
• Network Hardware Drivers
  (//os/drivers/:nhd.*)
• Physical Network Hardware
  (UltimateII+, C64Net, etc.)
• Commodore Network Protocol Server
  (e.g., services.c64os.com)
• Network Proxy Services
  (e.g., wikipedia, image conversion, etc.)
• Internet Services
  (e.g., websites, databases, etc.)

An Application that wants to use the internet loads in the main network library. Based on settings that you've previously configured using the Network Utility, the library loads in the appropriate driver. The driver communicates with the physical network hardware, and forms a connection to the Commodore Network Protocol (CNP) server. The Application then opens a socket connection to a network proxy service. The socket connection is provided by the library talking to the CNP server, by transferring through the hardware by means of the driver. The CNP server bridges that socket connection either to a final internet end point or, more practically, to a network proxy service.

The network proxy service fetches information from an internet service, such as a graphic from a website, and converts it to a format that is suitable for the C64. The data is returned through the stack and displayed to the user by the Application.

The network libraries packetize the data and exchange packets with the CNP server, and this allows multiple C64 OS Applications to each open one or more sockets to different internet services or proxy services, at the same time. Applications only ever open sockets, they never know about underlying hardware, its transfer speed, its communications protocol, etc.

Network Hardware

In order for network hardware to be usable by C64 OS, it needs to have a driver. C64 OS includes drivers for several devices and compatible device families at a variety of standard addresses.

Currently supported network hardware

Device	Comm	Interface	Speed	Network Interface	Driver
C64Net	RS-232	User Port	300 baud to 2400 baud	Wifi	up24.zi
C64 WIFI MODEM (RetroRewind)	RS-232	User Port	300 baud to 2400 baud	Wifi	up24.zi
UltimateII+	RS-232	Swiftlink @ $DE00	300 baud to 33.6 Kbps	Wifi / Ethernet	slde.u6
UltimateII+	RS-232	Swiftlink @ $DF00	300 baud to 33.6 Kbps	Wifi / Ethernet	sldf.u6
UltimateII+	RS-232	Swiftlink @ $DF80	300 baud to 33.6 Kbps	Wifi / Ethernet	sldf8.u6
Ultimate64	RS-232	Swiftlink @ $DE00	300 baud to 33.6 Kbps	Wifi / Ethernet	slde.u6
Ultimate64	RS-232	Swiftlink @ $DF00	300 baud to 33.6 Kbps	Wifi / Ethernet	sldf.u6
Ultimate64	RS-232	Swiftlink @ $DF80	300 baud to 33.6 Kbps	Wifi / Ethernet	sldf8.u6
Link232 Wifi	RS-232	Swiftlink @ $DE00	300 baud to 33.6 Kbps	Wifi	slde.zi
Link232 Wifi	RS-232	Swiftlink @ $DF00	300 baud to 33.6 Kbps	Wifi	sldf.zi
Swift-T/Swift-L Wifi	RS-232	Swiftlink @ $DE00	300 baud to 33.6 Kbps	Wifi	slde.zi
Swift-T/Swift-L Wifi	RS-232	Swiftlink @ $DF00	300 baud to 33.6 Kbps	Wifi	sldf.zi

Devices that use a combination of the physical hardware interface plus the identical firmware as a device listed above, should be able to use one of the drivers above. For example, Link232 consists of a SwiftLink-compatible cartridge, at configurable addresses, with a built-in Wifi modem with the Zimodem firmware. However, a real Swiftlink cartridge connected by an RS-232 serial cable to a generic Wifi modem with the Zimodem firmware, such as a modem intended for use with an Amiga or an Apple II, would work using the Link232 Wifi driver in C64 OS.

More drivers will be added in the future, but there are certain minimum requirements that the hardware needs to support.

The following are the minimum requirements from a network hardware device:

• Ability to open one TCP/IP socket
• Support for hardware flow control
• Bi-directional asynchronous communication

The following are not required but are useful to have:

• Programmatic ability to join Wifi hotspot
• Ability to disable local echo
• Ability to disable verbose responses
• NMIs when data is received
• NMIs when data is able to be sent

Driver Configuration

To set up the driver for your compatible network hardware device you will open the Network Utility.

The Network Utility can be opened from the Settings Utility. From the Utilities menu, choose Settings. From the hardware section, choose Network.

Settings Utility, available from the Utilities menu.

Driver Tab

The first tab of the Network Utility is for configuring the network hardware driver.

Network Utility - Driver Tab

When the Network Utility is opened for the first time, the selected driver is set to "none." Choose the driver to load by clicking the Driver cycle button. As with all cycle buttons, if you step too far, hold the COMMODORE key while clicking to cycle in reverse.

The driver names are made up of a series of codes. The first 2-letter code refers to the interface the computer uses to talk to the hardware.

• UP means User Port
• SL means Swiftlink
• T2 means Turbo232

The next 2-letter code depends on the hardware interface. The User Port uses more than one protocol, so the code refers to this protocol. Swiftlink and Turbo232 are cartridges or compatible interface chips mapped into I/O at certain addresses. The second 2-letter code for these devices refers to the address where they're found.

• 24 means RS-232 maximum 2400 baud protocol
• 96 means special 9600 baud protocol
• DE means $DE00 (or IO1)
• DF means $DF00 (or IO2)

The final 2-letter code is separate from the others by a dot (.) and refers to the device's firmware, its command set or command language.

• ZI means ZiModem
• U6 means Ultimate64 (compatible with UltimateII+)
• TR means TeensyROM

Code format of Network Hardware Drivers

Initial Baud / Maximum Baud

The next two sets of cycle buttons are labeled Ini.Baud and Max.Baud. The initial baud is the baud rate at which the modem communicates when it's powered on. This the baud rate that is saved in the modem's firmware. The maximum baud is the baud rate at which want the modem to operate. Usually this would be set as high as it can go, but there might be reasons for setting it lower.

Not all network hardware uses RS-232 to communicate with the computer. Any driver that does not communicate at a "baud rate" will ignore the values specified in these fields.

When communicating over RS-232 both sides need to agree on the communications speed. There is no way to auto-negotiate speed of an RS-232 connection, but C64 OS does perform a communications test by transmitting a command to the hardware and checking to see if the expected response was received. To begin communications the modem powers up to the initial baud rate, and the driver has to be set to that rate initially.

To step up to the maximum baud rate the driver transmits to the modem, at the initial rate, a command to change the modem's rate. The driver's own rate is then changed to match this, and a test is performed to ensure both sides can still communicate.

User Port modem baud rates

User Port modems are in the unique position of having RS-232 support built into the C64's KERNAL ROM. However, the KERNAL ROM's routines can only reliably communicate at 1200 baud. BASIC is also not fast enough to handle a continuous datastream at 1200 baud. There are reasons, therefore, why you might want your User Port modem to start up with a default speed of 1200 baud or even 300 baud.

For example, the C64Net modem (and compatible modems) come with a suite of internet programs written in BASIC (weather, IRC, FTP, wget, etc.) Leaving the modem communicating at 300 or 1200 at power up allows you to use these BASIC programs. But when you boot up into C64 OS the driver can easily step the modem up to 2400. This change is temporary; it's not written into the firmware. The next time you power up your C64, the modem is back to 300 or 1200, ready to be used from BASIC again.

Ulimate64 / UltimateII+ baud rates

The Ultimate64 and UltimateII+ have an emulated Swiftlink cartridge. The Swiftlink is built on the 6551 ACIA (Asynchronous Communications Interface Adapter.) Normally the 6551's speed has to be set, plus the communications speed has to be sent to the modem, as described earlier.

This is not the case with the Ultimate64 and UltimateII+. Because these devices emulate both the 6551 ACIA and the modem, the emulated modem's speed is always synchronized to the speed set in the emulated 6551's registers. This makes communications at any speed very reliable. It doesn't matter what initial or max baud rates you set, as long as the correct driver has been chosen for the address where the emulated Swiftlink is at, communications will always succeed and run at the maximum speed specified.

Save to load driver

When you cycle the button to a different driver, the status message beside the test button says "unsaved" and the test button is disabled.

You must click the Save button to load the selected driver. Saving saves all the current settings in all three tabs. It then loads the selected driver and begins trying to configure and step up the baud rate and it tests for successful communications.

If the test is successful, the status message beside the test button says Pass, if the test cannot communicate with the modem, the status message says Fail.

How to safely change hardware

It will happen at some point that you want to change your network hardware. Either you want to change the address where a SwiftLink is found, or you update from a User Port modem to a nice internal Swift-L modem, or you just boot a copy of C64 OS that was installed on one C64 on a different C64 with a different set of hardware.

As mentioned earlier, having the wrong driver loaded means it will try writing to the registers of a chip that either isn't there, or worse to something else that's at that address. The safest and most convenient way to change hardware is to plan ahead. With the current hardware still installed, open the Network Utility, cycle the driver button until it says "None" and click Save. This will uninstall any currently loaded driver.

Shut the computer down and change the hardware. When you boot back up and run the Network Utility again, it is configured for no network hardware driver. None will be loaded and you can proceed to pick the correct driver for your new hardware.

If you have already changed the hardware but you forgot that the networking driver for the old hardware is still configured, you have two options:

You can hold the CONTROL key down while the Network Utility is opening. This will prevent it from attempting to load and configure the driver that is saved in settings. This keyboard shortcut is not easy to discover, but it does follow a pattern. Numerous other Utilities have alternative behavior if they're run with the CONTROL key held down.

As a last resort, you can scratch the network settings file:

//os/settings/:network.t

This file is automatically rebuilt the next time you load and run the Network Utility. Without this file, the driver is automatically reverted to none. However, if you delete this file you will also lose other saved networking settings.

Wifi Hotspot

The second tab in the Network Utility is for Wifi. Even if your hardware is Ethernet-based and does not require a connection to a Wifi hotspot, the network configuration requires that something be filled into these fields. In this case, fill in anything and click Save.

Standalone Wifi modems provide a command that can be used to get the modem to join a Wifi hotspot. You provide the SSID and password for a local hotspot, and the network hardware driver sends the commands for you.

The Wifi hotspot to connect to is not saved to the modem's firmware. Therefore, if you use some other telecommunications software to talk to the modem and configure it to join a hotspot automatically, when the C64 OS networking stack boots up, it sends the command to the modem again to join the hotspot you've specified in the Network Utility. This can be different from the one saved in the modem's firmware.

Network Utility - Wifi Tab

After joining a hotspot, the driver requests the name of the hotspot to which the modem is connected and displays it beside the status label. Not all hardware is capable of requesting the current SSID from the network hardware. In this case, the driver returns a fake SSID.

Ultimate64 and UltimateII+ can use either Ethernet or Wifi. However, neither can be configured by software running on the C64. This is for security reasons, since the network configuration on one of these devices provides network services at a lower level, and not just for the C64 itself to go online. On these devices, use the backend menu system to configure the Ethernet or Wifi connection. In the Network Utility, enter any bogus SSID and password and click Save. The status will show it's connected to an SSID called "Ultimate".

Upon opening the Network Utility, if you've already booted the network stack and the modem has already been commanded to join a hotspot, it will not automatically request the name of the hotspot again. Click the refresh button to manually request the current SSID. This can be useful when you're already connected to an SSID but want to change to another.

It is possible to enter an SSID and password, and click Join and successfully join that Wifi hotspot, without having saved these settings. This can be done, for example, to temporarily join a different hotspot. To restore the SSID and Pass fields to the way they are saved, click the Reload button. Clicking Reload does not change what SSID you're connected to, it just reloads the fields from saved settings. To join that SSID, click Join again.

If you're satisfied with the current SSID and password settings, click Save to save these as the default hotspot for C64 OS to join automatically next time.

CNP Account

The third tab in the Network Utility is for configuring the address to a Commodore Network Protocol (CNP) server and for providing your access credentials to that server.

Why do we need a CNP server?

You can conceptually think of the CNP server the way you thought of the PPP server run by your dial-up ISP in the 1990s.

Most modems that do TCP/IP on behalf of the C64 only allow a single socket connection at a time. There are some exceptions to this, but if C64 OS relied on the special abilities of just some modems, that would preclude the use of all the others. A single TCP/IP socket connection is conceptually similar to a dial-up modem being able to dial up to just a single other modem.

By running PPP (point-to-point protocol) over that single dial-up connection, many TCP/IP sockets can be open at the same time on the computer, and the packets are routed via PPP to the other end which forwards them to the internet. The Commodore Network Protocol is different but similar. The network hardware driver commands the modem to open a single TCP/IP socket connection to the CNP server. And the CNP library in C64 OS provides a socket API to Applications that allow many sockets to be open at the same time. The Commodore Network Protocol receives and transmits packets to the CNP server, which forwards them to the internet.

CNP Server, hosted by OpCoders Inc.

The Commodore Network Protocol was designed and implemented by OpCoders Inc. The client side is implemented in the CNP library (//os/libraries/:cnp.lib) which was first released as part of C64 OS v1.07. The server side was implemented in NodeJS with a MySQL database for client authentication.

OpCoders Inc. hosts an instance of the CNP server, along with a growing set of proxy and conversion services designed to help the Commodore 64 consume content from the internet. This suite of services together is referred to as C64 OS Network Proxy Services. OpCoders Inc. sells a subscription to the Network Proxy Services, collectively, for a small monthly fee with a discount if the subscription is paid for annually.

The subscription to the hosted Network Proxy Services is only available to licensed C64 OS users. You can sign in to your account at c64os.com here. User accounts at c64os.com are created implicitly with the purchase of a commercial license to use C64 OS, although the account needs to be activated by resetting the password before logging in the first time.

Once logged into your c64os.com account, you can subscribe to the Network Proxy Services and manage your CNP access credentials here.

Manage your CNP access credentials

To create and maintain your CNP access credentials, use a PC, Mac, tablet or smartphone to sign in securely to your c64os.com account. Instructions found under the CNP access section of your account provide the hostname and port of the CNP server. You input these, along with your CNP username and password, into the Network Utility's CNP tab in C64 OS. Click Save to save these settings.

The CNP username and password are transmitted unencrypted by the C64 to the CNP server, over the internet. However, your CNP username and password are fully independent of the email address and password used to log into your c64os.com account. The CNP username and password are used exclusively to authenticate your copy of C64 OS with the CNP server hosted by OpCoders Inc.

Network Utility - CNP Tab

If you are technically-minded and you do not want to pay for the hosted Network Proxy Services, the CNP server has also been open-sourced. Other proxy services hosted by OpCoders Inc. will be added to this repository as they become available. The CNP server is written in NodeJS and can be hosted on a local computer or on your own cloud infrastructure.

Starting and Stopping the CNP connection

With the Network Utility open, the driver configured, the Wifi connected, and the CNP host, address, username and password filled in, you can click the Start button to start the CNP connection.

All of the controls in all three tabs become disabled, except the Stop button in the CNP tab. It isn't possible to change these settings while online. To change settings, click Stop to end the CNP connection. All the buttons then become available again.

After clicking Start, if the buttons become available on their own a couple of seconds later, this is because either the connection to the CNP server cannot be established or the access credentials are being declined. Confirm that the host and port were input correctly. Confirm that your username and password were input correctly. If in doubt about what your username or password are, confirm your username in the CNP Access section of your account at c64os.com, and assign a new password if necessary.

Automatic network boot

You only need to use the Network Utility when initially setting up your network settings or later if you need to change something. For example, if your Wifi router's SSID or password are changed, you can use the Network Utility to update those settings.

Once the network settings are saved, you do not need to open the Network Utility every time you want to go online. Simply open an Application or Utility that uses the network. The network library reads in your saved settings and performs a full network boot, automatically.

After freshly booting up C64 OS, the first time you open an Application or Utility that needs to use the internet, you need only wait a couple of seconds while it establishes the connection. Use the system status bar to see your offline status change to online.

Status Bar - Status Mode - Online

Managing Connection

There are a few things to be aware of to maintain the network connection and what to do if the network connection is lost.

The C64 OS network stack is tiny and efficient by modern standards, but it requires a non-trivial amount of memory on a computer with only 64KB of RAM.¹ For this reason, the network stack is only loaded into memory in an App bank where something needs to use it. Therefore, if you are in an Application, like Wikipedia, the network stack is loaded into that App bank. But if you fast app switch back to File Manager, the network stack is not loaded in that App bank.

The TCP/IP modem hardware is intelligent. It can maintain a TCP/IP connection with the CNP server without active intervention from the C64. When the network stack is frozen in an App bank in the REU, it's not active and cannot respond to incoming data. When the App is being frozen the network driver is instructed to pause the network. A typical driver does this by asserting hardware flow control. This is one reason why hardware flow control is a requirement from network hardware under C64 OS.

If you switch from one App that uses networking to another that also uses networking, the network driver pauses the data flow while the first App is outgoing, but then the incoming App resumes the data flow again. When the network stack is not loaded in, it cannot possibly handle incoming data, because the driver code is just running. A similar situation occurs if you quit to BASIC, or use PRG Runner to launch into non-C64-OS software. The network stack has the driver pause the network data flow before leaving C64 OS. When you fast reboot into C64 OS, and an App that uses the network stack, the network data flow is resumed.

While the network stack is loaded and running, it sends a keep alive message to the CNP server after every 60 seconds of no other network activity. This keeps the network connection alive indefinitely. However, when the network stack is not running, such as when frozen in an App bank or when you drop to BASIC, keep alive messages are not being sent. The CNP server drops the connection after 10 minutes of inactivity. It does this so that, if you simply turn off your Commodore 64 and walk away, ten minutes later the CNP server close the connection, closes all open sockets and cleans up and reclaims any resources that connection was using.

Unfortunately, if you using C64 OS, but you switch to an Application without the networking stack and stay there for 10 or more minutes, then connection will be closed automatically and any open sockets in background Apps are closed.

If you switch back to a network-using Application but the CNP server connection has been closed, the network stack should open the Network Utility automatically. Simply click the Start button in the CNP tab to go back online. You can then close the Network Utility and carry on.

---

Wikipedia

The Wikipedia App, otherwise known as Wikipedia C64 OS edition, is the main Application that makes use of networking in C64 OS at the time of its release as part of version 1.07.

New Applications that use the C64 OS networking stack are being worked on and released as separate App downloads. Check the C64 OS Software Releases for other C64 OS software.

Loading Wikipedia for the first time, we see this nice loading screen with its icon and its catch phrase.

Wikipedia - Loading

After Wikipedia has loaded in, we see the welcome text in the article viewer and the empty table of contents on the left.

Notice that in the status bar it says we're currently offline. At this point the network stack is booting, the driver is being configured, the modem is connecting to the Wifi hotspot and the CNP server connection is being established, all automatically.

Wikipedia - Initially Offline

After a couple of seconds the status bar changes to say "Online". And we're ready to start browsing Wikipedia and using our beloved Commodore 64 to learn about the world around us.

If you're anything like me, you can sink many hours into reading about obscure topics like the history of the popes of Rome; who was Jessica Jones married to in the comic books? and when was it exactly that Jack Tramiel bought Atari? Doing this from your C64 feels amazing.

Wikipedia - Goes Online Automatically

Enter a topic in the search field and press RETURN or click the Search button.

The status bar shows the percentage download progress in Application Custom Message mode. Click on any subtopic in the table of contents to jump to that section of the article. Click a link, highlighted in red, in the main article to jump to that new Wikipedia article.

Wikipedia - Article about the 6502

You can save any article section to a file for offline viewing, or to open and edit later, by choosing Quick Save from the File menu, or press CONTROL+COMMODORE+S.

Articles are saved to a Wikipedia subdirectory of your Documents directory. Article files are named by the first part of the search field followed by an index number from the position in table of contents.

Wikipedia - Quick Save

Explore the other menu options for ways to navigate the article and the user interface using keyboard shortcuts. You can hide the search bar and table of contents to maximize the viewing area of the article, and move up and down the table of contents even when it's not showing.

From the Language menu you can choose from up to 6 languages:

• English
• German
• Spanish
• Esperanto
• French, and
• Italian

And enjoy a little bitmapped branding by choosing the Wikipedia splash screen from the View menu.

Wikipedia - Different Languages (left) - Splash Screen (right)

Enjoy Wikipedia on your Commodore 64. More to come.

---

This concludes Part I.

In Part I we have covered what hardware C64 OS supports, how to identify and choose the right driver, and how to configure your settings for joining a hotspot. We also covered the basics of what the Commodore Network Protocol is and how to manage your access credentials. How to use them to get online, and a quick overview of how to use the Wikipedia Application.

Part II of this guide has a more philosophical and a more technical approach. It covers in more detail how the Commodore Network Protocol works and what kind of Applications we can expect from the future on C64 OS.

Part II: Commodore Network Protocol

1. Driver:	3 to 5 pages
   CNP Library:	4 pages
   Network Library:	5 pages

   
   Total: 12 to 14 pages, or ~5% of total memory.

Table of Contents

This document is subject to revision updates.

Last modified: Jan 06, 2025