The Manual

• Telnet BBS on port 23 (configurable), 80x25 ANSI with CP437 art, tested with SyncTERM.
• Two complete looks: Axis (drippy orange) and Oblivion (grey and cyan, in the style of Oblivion/2), switchable with one tap. Sysop art packs drop in from the SD card.
• Accounts with a new user application, validation, security levels, permissions, a time limit and an idle logoff.
• File areas on a microSD card with ZMODEM, XMODEM and XMODEM-1K downloads and uploads, an upload checker, archive listings, search, new files and a download ratio.
• Message areas with quoting and taglines, a new message scan, and private email.
• Oneliners, rumors, a BBS list, top ten, a voting booth, last callers and a bulletin.
• Several callers per board, and several boards on one LAN joined into one BBS: teleconference, node messages, broadcasts and live split-screen chat between callers.
• Native LORD (Legend of the Red Dragon in C++, over telnet), an ANSI pack viewer with ANSI movies, and a password-locked DOS prompt. An unmodified DOS EXE is a separate PC build, not this firmware.
• A touch sysop console on the board itself: activity screen, node details with KICK, user validation, settings, logs, SD formatting, and a local login on the 2.8 inch screen.

The firmware builds with PlatformIO. Install it (the VS Code extension or the command line), clone the repository, plug the CYD in over USB, find its COM port, and run:

git clone https://github.com/revjmoney/axis-bbs.git
cd axis-bbs
pio run -e cyd -t upload --upload-port COM5

Use your own port name (COM5 on Windows, something like /dev/ttyUSB0 on Linux). The cyd environment is the default, so pio run -t upload does the same. Other environments are covered under headless nodes and building.

On first boot (or whenever no saved network is in range) the board opens a touch WiFi picker. It lists the networks it can hear, strongest first. Tap yours, type the password on the on-screen keyboard (it is masked; SHOW reveals it) and press OK. HIDDEN lets you type a network name that does not broadcast, RESCAN looks again and MORE pages the list. The network is saved only after the join works, and the board remembers up to five networks.

The sysop handle and password from the wizard are the main sysop account. Log in with them over telnet and you get "Sysop access": no time limit, every area visible, and the sysop-only commands (the user editor *, forcing a caller into chat, asking voting booth questions). You can also make any caller a sysop later; see sysop promotion. On the board, the LOCAL button logs you in as the sysop without a password.

On the same LAN the board announces itself over mDNS, so callers dial the board name with .local:

syncterm telnet://axis.local
telnet axis.local 23

If a computer cannot resolve .local names, use the board's IP address instead. The board shows it on its activity screen ticker and in SYSTEM on the sysop menu, and callers see it with I (system info).

With a cluster, callers always dial the main board. When every node on the main is busy, it passes the new caller through to the lowest free node on another board, so one address serves the whole system. See multinode and clustering.

The BBS was built for the LAN first. To let callers in from outside, forward a port on your home router to the main board:

1. Give the main board a fixed address. In your router's DHCP settings, make a DHCP reservation for the board's MAC address so its LAN IP never changes.
2. Forward a TCP port to that address, port 23 (or whatever telnet_port is). You can forward outside port 23 straight through, or use a different outside port such as 2323 and point it at the board's port 23. A non-standard outside port cuts down on bot traffic.
3. Tell callers the address. Put your public hostname in public_host; the Oblivion look's front door shows it as the dial address. A changing home IP can be followed with the optional dynamic DNS extra (No-IP, asked by the wizard, or GoDaddy).

Only one session can be in a door or a file transfer per board at a time. If a second caller on the same board asks, they are told the door is busy and to try again (or call back, since they may land on a free node).

• On the board: tap the activity screen, open BBS SETUP and tap THEME. Each tap moves to the next look: axis, oblivion, iniquity.
• On the serial console: @SET theme=iniquity, theme=oblivion or theme=axis.
• In /axis.ini: theme=oblivion. Any value other than oblivion or iniquity means axis.

The main board sends the change to every board in the cluster at once. The next screen each caller gets is in the new look.

Each area is a folder: /sd/files/<id>/, where the id comes from the area's setting. The board makes the folders for every listed area when it starts. Inside each folder, an optional FILES.BBS gives the descriptions, one file per line: the file name, a space, then the description.

/sd/files/gcode/FILES.BBS
SPIRAL.NC     Spiral flute toolpath for a 4th axis, 1/4 inch end mill
LOGO.NC       AXIS logo, 2D pocket, 3 mm deep

FILES.BBS is optional: files in the folder without a line still show, after the listed ones, with no description.

Areas are set with areaN=id|name, areaN=id|name|level or areaN=id|name|level|m (m: mirrored onto two SD cards when the cluster has them; see SD card clustering). They are sorted by the number N, and a repeated number replaces the earlier one, so @SET area0=new|New Uploads adds an area at the top. The optional level is the lowest security level that can see the area at all; callers below it never see it (the sysop sees everything). If no areaN lines are set, the default list is used:

At the area list, type an area number and Enter, or:

• N new files since your last call
• / search every area
• Enter back to the main menu

Inside an area, files list 15 to a page with their size and description:

• N next page
• P previous page
• V view a text file
• I info on a file
• D download
• U upload
• Q back to the area list

V shows text files (TXT, NFO, DIZ, ANS, ASC, BBS, DOC, MD, 1ST) a screen at a time.

/ at the area list searches the names and descriptions in every area you can see, case-insensitive, and groups the hits by area (up to 60 shown). N lists every file that landed since your previous call, by the file dates on the card; on a first call it shows the last seven days.

Downloads are earned. A new caller can browse the lists and use Info, but Download and View wait until they have uploaded something. The sysop can wave this for one caller with FREE DL (on the CYD under CALLER, ACCESS, or with L in the telnet user editor).

On top of that you can set a ratio: with ratio=3 and free_kb=512, a caller can download up to three times the bytes they have uploaded, plus a 512 KB allowance. ratio=0 (the default) means no ratio. FREE DL skips the ratio too. Upload and download bytes are counted on every account and shown in the user editor and on the node detail screen.

Areas are set with msgareaN=id|name or msgareaN=id|name|level, with the same numbering and level rules as file areas. The 16 defaults: General Chatter (general), CNC Shop Talk (cnc), Routers & Gantries (routers), Mills & Lathes (mills), 4th & 5th Axis (rotary), CAM & G-code (cam), Controllers & Electronics (controls), Tooling, Feeds & Speeds (tooling), Workholding & Fixtures (workholding), Lasers, Plasma & 3D Printers (lasers), Show & Tell (showtell), Crashes & Fails (crashes), Buy, Sell & Trade (trade), RotatoCAM (rotatocam), BBS Scene & ANSI (scene) and Ask the Sysop (sysop).

Type an area number to open it. The newest page of headers shows, with a * beside messages you have not read. The board remembers where each caller got to in every area.

• R read a message by number
• N next new message
• P post a new message
• A reply to the one you are reading
• L list the headers again
• Q back to the areas (Enter there: main menu)

Posting asks who it is to (Enter for All) and a subject, then you type the body a line at a time (up to 76 characters a line, 99 lines). /S on a line by itself saves, /A drops it.

A reply starts with up to 8 lines of the original, each with the writer's initials in front, the way old boards did it: SK> .... The subject carries over (Enter keeps it). If you have a tagline set in user settings, it signs every message and email you write: ... your tagline.

S at the main menu (! with the O/2 letters) walks through every message area open to you, one new message after another, then says you are all caught up. If nothing is new anywhere it tells you right away.

After login the newest 10 oneliners show and the caller may add one (60 characters). The board keeps the newest 20. O at the main menu brings the wall back up.

Anonymous one-liners, like the old days. R opens them: A adds one (70 characters, nobody sees who wrote it), L lists the newest 15, Q quits. A random rumor shows above the main menu prompt.

B shows the boards your callers call: name, address and a few words about each. A adds one (name, address as host:port, about it), Q quits. The list and the rumors keep 50 lines each.

K ranks validated callers two ways: most calls, and top uploaders by kilobytes.

V lists the questions (up to nine shown). Type a question's number to see the tallies with bars and cast your vote; each caller votes once per question. Only the sysop can ask: A, type the question, then the choices one per line (2 to 6), and an empty line to finish.

Every login goes on a list of the newest 20 (handle, node, time, location). L shows the newest 12, newest first (w with the O/2 letters).

sessions sets how many callers a board takes at once: 1 to 4, default 2 on a CYD (a headless node defaults to 3). Each session is its own node number; the activity screen shows them as, for example, node 1+2. Native LORD does not take the single door slot, so more than one caller on the same board can be in it. The ANSI viewer, the DOS prompt, and a file transfer still share one slot per board. Everything else (menus, messages, chat, browsing) runs side by side.

Flash another board, put it on the same network, and it finds the others by itself (mDNS service _axisbbs._tcp plus UDP broadcast). The one thing to set is the shared cluster key: from version 0.51 boards only link with boards that hold the same key.

• The SD board is main and node 1. The board with the SD card is the main: it owns the files, messages and lists, and serves them to the others over the link. A main without a card hands the role to a board that has one as soon as it joins. More boards with cards add their cards to the file areas; see SD card clustering.
• One set of settings. Every other board takes the main's settings over the link, keeping only its own board_name, sessions and telnet_port. A change on the main (from @SET or the THEME button) reaches every board at once.
• One user base. Every board keeps the whole user base. Changes travel as single records, so a new account or a password change on any board is on all of them a moment later.
• Node numbers. Each board gets one number per session and keeps it across reboots. Once every node has been idle for 10 seconds (the local console counts as busy), the main renumbers the cluster so its own sessions are 1, 2 and so on, then each other board in order, closing gaps like "2+4".
• Failover. Boards trade a heartbeat every second. If the main goes away, the next board takes over within about 5 seconds; the board with the SD card always wins the main role back.
• Caller relay. Callers dial the main. When every node on the main is busy, it passes the caller to the lowest free node on another board, passing the bytes both ways untouched.
• Doors on other boards. A board without the door files runs native LORD locally and reads the main's door folder over the link, with the main's record locks, so every node shares one PLAYER.DAT.

Boards only join a cluster when they share a secret, the cluster key. Discovery is signed, a new link proves the key in both directions, and every frame on the link carries a tag, so a stranger on your network cannot join, forge, change or replay what the boards say to each other. A board with no key runs alone.

1. Pick a secret of 8 or more characters. The same one goes on every board. Keep it somewhere private; do not post it or commit it to a repository.
2. Connect to each board over USB and open its serial console at 115200 baud.
3. On each board type @CLUSTERKEY followed by a space and your secret, then Enter. Or use the cluster key line in the sysop menu's System layer on the board itself.
4. Check it: @CLUSTERKEY alone says whether a key is set (it never shows the key). @CLUSTERKEY off clears it.

• Stored on the board only. The key lives in that board's own storage, not in axis.ini, and is never shown or sent in the settings sync. You enter it once per board.
• Upgrade rule: older firmware cannot join a keyed board. Flash every board with 0.51 together, then give each the same key. A board on 0.51 with no key runs alone until it has one.
• Replacing a board? Flash it, then set the same key on it. Changing the key means setting the new one on every board.

Put an SD card in more than one board and the cards work together. There is nothing to set up for the pool; mirroring is one letter per area.

• Every card adds to one library. The main lists each area across every card in the cluster as one list. A file that is on two cards shows once (the larger copy, if they differ), with the description from whichever card has one. Callers on any board, with or without a card, see the same lists.
• Uploads go to the roomiest card. A new upload is written to the card with the most free space, its own or another board's, and its FILES.BBS description goes on that card. Downloads read from a card that has the file, the main's own card first.
• Mirrored areas keep two copies. Add |m to an area line (area3=gcode|G-code and Toolpaths|0|m) and the main copies every file in that area that only one card holds onto a second card with room, in the background: one file at a time, 2 KB per turn of the main loop, so callers never notice. A copy only shows up once it is whole.
• When a board is down. Its card simply drops out of the lists until it comes back; nothing waits on it longer than a couple of seconds. A file in a mirrored area is still there from its other copy. A copy cut short by a board leaving is thrown away and made again on a later pass. The sysop's remove and rename reach every copy that is up.
• Checking on it. On the main's serial console, @CARDS lists each card board with its free space and whether it is up, and @MIRROR shows the mirrored areas and what the mirror is doing (copying, resting, how many copied or failed, the last event). Mirror copies also go in the event log ("mirror: copied X to node 2").

With one SD card in the cluster (the usual setup) everything works exactly as before: the main's card is the library.

Every SD card becomes a disc in a CD-ROM changer, the way a Night Owl shareware CD worked on a 90s board. Swap cards and the file areas follow.

• A card is a disc. Only the card's /files folder is the disc; each subfolder with files in it is one area, named after the disc (NIGHTOWL 12: Games). The disc name is the card's volume label. The rest of the card stays free for anything else.
• Hot swap. Pull a card out of any board or push one in and, within a few seconds, every node gains or loses that disc's areas, with a DISC IN or DISC OUT toast on the screens and a notice to callers online. A blank card does nothing until files show up in its /files.
• FILE_ID.DIZ built in. A file with no description gets one from the FILE_ID.DIZ inside its archive, read once when the disc goes in and saved with the disc. A FILES.BBS description wins.
• Never merged. The same folder on two discs is two areas.
• The main's card too. Its message bases and doors will be backed up on another board's card, so pulling it keeps the BBS running from the backup; uploads land on the backup meanwhile and are combined back when the card returns. The main stays main.

Design: docs/superpowers/specs/2026-11-04-sd-disc-changer-design.md. Plan: docs/superpowers/plans/2026-11-04-sd-disc-changer.md.

T joins the teleconference with every node. Lines go through the main so every node sees them in the same order, each tagged with the node and handle. Type /Q to leave.

P (or Y) asks for a one-line message for the sysop. It shows as PAGE on every CYD's activity screen for a minute, sets the PAGE light and the magenta LED strobe, and goes in the event log.

N at the main menu (= with the O/2 letters) opens the Oblivion/2 style multinode commands. They work across boards.

• M message one node (a private one-liner)
• B broadcast to every node
• S split-screen chat with a node
• A available for chat on or off
• F force a node into the teleconference (sysop)
• W who's online
• Q back to the main menu

Type the node number when asked; Esc gives up. A note or broadcast that arrives while a caller is in a door or a transfer waits for their next menu. With availability off (do not disturb) a caller gets no notes, broadcasts or chat requests, and shows (DND) in who's online. A forced caller is pulled straight into the teleconference if they are at a menu, otherwise they get a note asking them to join with T.

Pick S and a node number. The other caller is asked whether to accept (Y/N). If they do, both screens split: their keystrokes appear live in the top half, yours in the bottom, each key sent as it is typed. Each half wipes itself when it fills. Esc ends the chat for both.

The ESP32 image runs doors that are built into the firmware. A program name that starts with * is one of those. Native LORD is *LORD. The ANSI viewer is *ANSIVIEW. The DOS prompt is *DOSSHELL.

• Native LORD does not take the single door slot, so two callers on the same board can both be in it. See Native LORD.
• The ANSI viewer and the DOS prompt do take that slot. A second caller is told the door is busy.
• An .EXE does not run on this image. The caller is told the DOS runtime is not in this firmware. That runtime is the separate PC build. See the DOS emulator.
• Time. A door session is limited to daily_minutes.
• Files. Native LORD reads /doors/lord/ on the SD card (the main board's card, for every node).

doorN=id|name|exe|args|drop
door1=lord|LORD|*LORD||none
door2=ansiview|ANSI Pack Viewer|*ANSIVIEW|ansi|none
door3=dos|DOS Prompt (password)|*DOSSHELL|dosbox|none

The DOS Prompt is always added if a saved list leaves it out. A saved list that has no *LORD row gains one named LORD. An old LORD.EXE row can stay in the file, and this firmware will not start it.

A caller who types a handle nobody uses is asked whether to apply (in the Oblivion look, Apply on the matrix does the same). The application is about twenty questions in sections. The sysop reads every answer; with new user voting on, the callers who vote read them too, except the first name and email:

• About you: a password (6 or more characters, twice), first name, location, email (optional), how they heard about the board.
• The shop: do they own a CNC (router, mill, lathe, laser or 3D printer), the machine and controller, what they cut, whether they know someone with one, a rotary (4th) axis.
• RotatoCAM: do they know it, are they a RotatoCAM Pro user, have they been to rotatocam.com and jmscnc.com, what CAM software they use.
• The scene: first BBS, best ANSI group, their terminal, what they would upload, why they should be let in.
• The rules, then review and submit.

Validated callers vote applicants in or out, the way Oblivion/2 and ViSiON/3 boards did. A caller who may vote is asked at login when someone is waiting ("Vote now?", the CHECKNUV step of the login sequence; on the built-in menu a notice says so), and A on the built-in menu (N on an Oblivion/2 menu, RUN:NUV in a menu file) opens it any time. Each applicant shows their handle, location, the votes so far, and their answers. Yes or No, then an optional word for the other voters; Skip leaves them for later, Quit goes back.

• nuv_yes yes votes let an applicant in (security raised to at least 20, a LORD warrior made). nuv_no no votes turn them down; they are told the vote did it. Set either in the sysop menu, Settings, Callers and limits.
• Only validated callers at nuv_level or above vote, never on themselves, once each (a second vote replaces the first). Twits don't vote. The sysop votes too.
• A pending applicant's status screen shows their tally. Votes are kept on the account and travel the cluster link; two boards voting at once keep both votes.
• The sysop can still validate or deny anyone at once. nuv_yes=0 turns voting off.

• On the CYD: tap the activity screen, USERS (pending callers are listed first), tap a caller to read every answer, then VALIDATE or DENY.
• Over telnet: the sysop user editor (*), V or D. Validating raises security to at least 20.
• On the serial console: @ADDUSER handle|location|password adds a caller who is already validated (security 20, password 6+ characters).

• Security level (0 to 255). File and message areas can require a level (areaN=id|name|level); callers below it never see the area. 255 is a sysop.
• Permissions: each caller has files, messages and doors switches, all on by default. A caller with one off is told that part is closed to their account.
• Free downloads: skips the download gate and the ratio.

On the CYD these are under USERS, a caller, ACCESS: toggles for FILES, MSGS, DOORS, FREE DL and SYSOP. Changes are saved and synced to every board.

daily_minutes (default 60) is enforced per call: at 5 minutes left the caller sees a warning, and at zero they are logged off. The Oblivion prompt shows [N left]. A door session gets the same limit. The sysop is exempt. idle_minutes (default 5) logs off a caller who types nothing for that long, including during the application; doors and transfers are not counted as idle.

The quiet way to deal with a problem caller. A twit's message posts are hidden from everyone but them and the sysop, and their oneliners, rumors and teleconference lines reach nobody but them. They are told it all worked. Toggle it with T in the user editor.

Any user at security 255 is a sysop: no time limit, every area, and the sysop commands. Promote a caller with @SYSOP handle on the serial console, the SYSOP toggle under ACCESS on the CYD, or security 255 in the user editor.

When idle the board shows a Renegade-style waiting-for-caller screen drawn in the board's look: a title bar with the version, the board's nodes with who is on, the numbers for today and a row of sysop keys. Its live values (calls, posts and uploads today, free RAM, uptime, the last caller, every node) come from pipe codes in the art, so each look draws its own. The same screen appears in four places: on the touchscreen (45x24 in 7x10 pixel cells), for a sysop over telnet, on the panel console and on the serial console (80x25).

• On the touchscreen tap a key's label to use it, or tap a node's line for its detail screen (the caller, time online, IP, calls and transfers, with BACK and KICK). The art stays on screen while the WFC is up.
• Over telnet, on the panel and on the serial console the WFC opens for a sysop (on serial, type wfc). A line starting with @ leaves it for the command prompt, and ten idle minutes close it. Over telnet it needs the sysop_telnet setting on (the default); with it off, sysop screens stay on the board's own screen and serial.
• The counters for calls, posts and uploads today roll over at local midnight.
• No art for the look? A built-in WFC is used, so every board has one.

Every one of the eight looks (axis, crt, haunted, sea, cathedral, skulls, underground and wasteland) comes with its own WFC art, drawn in that look's colours: WFC.ANS at 80x25 and WFCCYD.ANS at 45x24 for the touchscreen. The skin is its own setting, wfc, kept apart from theme. Leave it blank and the WFC follows the theme; set a look's id and the WFC keeps that look whatever the callers see. Change it under Settings > Look in the sysop menu, or with @SET wfc=sea.

Your own skin goes in /sd/themes/<look>/ as WFC.ANS and WFCCYD.ANS. The pipe codes for live values are listed in docs/WFC-CODES.md in the repository.

The WFC takes Renegade-style single keys, and online a sysop reaches the same places by typing //.

Online, a sysop types //U (and the other letters) to land straight in that section of the sysop menu. // alone opens the WFC at the board, and the sysop menu over telnet; there its "Waiting for caller screen" item shows the WFC, and Q or Esc goes back to the menu (it never hangs up). E (events), A (archive) and ! (validate) say "coming soon" for now. Over telnet // works only while sysop_telnet is on.

Tap a node's line for its detail screen: the caller, what they are doing, time online, their IP, whether they are a sysop, their calls and upload and download totals. BACK returns; KICK hangs that caller up (and logs it). The WFC's other keys open the sysop menu.

The sysop menu is part of the BBS itself: lightbar screens in the board's look, one menu for every screen: online, on the board's touchscreen, on the panel console and on the serial console. Online, press * at the main menu or type // (sysop only; see sysop keys). On the board, tap a key on the WFC (S, U, #, B, F or L) to land on that layer, and tap a line to pick it. Move with the arrow keys or the item's number, Enter picks, Q or Esc goes back a layer, N/P page.

Every change goes through the same @ command the serial console uses, and runs on the main board, which shares it with every board. A follower board passes its sysop menu's commands to the main.

A small app for your PC, python tools/panel/run.py, finds every board on your home network and serves a control panel to any browser on that network, PC or phone, at http://<your pc>:8326/, with a tray icon. Log in with the sysop password (or any security 255 user); the password never crosses the network.

• Nodes, Users, Settings, Lists, System: the same controls as the sysop menu, built from whatever is online.
• Wall: every node's screen, live, like a security camera wall.
• Console: open a new sysop session on any board, or break in on a caller (they are told when you join and leave).
• Each board's panel port is TCP 2326, LAN only, one panel at a time. Three bad logins from an address lock it out, as for telnet.

The headless-ring build drives an eight-light ring (reds on GPIO 23, 19, 12, 25 and greens on 22, 18, 14, 33) as a cluster status ring:

• A comet with a fading tail runs round the ring: slowly when idle, fast when callers are on.
• A door running: the comet runs on the four reds only. A transfer: on the four greens only.
• Teleconference: two comets chase each other.
• New users waiting: a green flash every 2 seconds.
• The main lost: the reds breathe slowly.
• The sysop is paged: every red flashes four times a second.

A plain headless board shows the RGB patterns as brightness on its single LED (GPIO 2).

tools/sdput.py copies a folder onto the board's storage over the serial port and checks every file's byte sum. From Git Bash on Windows, put MSYS_NO_PATHCONV=1 in front so the board path is not rewritten into a Windows path.

python -I tools/sdput.py COM5 my-files /files/text --baud=921600

The same on every board (partitions.csv):

LittleFS keeps its offset and size across releases, so a new flash never loses users, settings or logs.

FAT32. The board checks for a card at boot and uses it for storage if it answers, otherwise internal flash. FORMAT SD (or @SDFORMAT FORMAT) makes a fresh FAT32 volume.

/sd/files/<area id>/     file areas, each with an optional FILES.BBS
/sd/doors/lord/          native LORD data (warriors, gear, ANSI scenes)
/sd/themes/<theme>/      MATRIX.ANS, MAIN.ANS, BULLETIN.ANS
/sd/dosbox/              the DOS Prompt sandbox (16 MB at most)

PlatformIO, the espressif32@6.9.0 platform, the Arduino framework and LovyanGFX. Three environments:

Same tree, two builds. CMakeLists.txt follows IDF_PATH.

• Board. pio run -e cyd (or headless, headless-ring). PlatformIO sets IDF_PATH. The image is src/, including src/lord/. dosemu/ is not linked.
• PC. Leave IDF_PATH unset. CMake includes CMakeLists.pc.txt, which links dosemu/, third_party/i8086, and the native engine. You get axis_tests, doorhost, and xfertest.

cmake -S . -B build -G Ninja
cmake --build build
build/axis_tests

On Windows use MSYS2's g++ and Ninja. How to run an unmodified EXE is on the DOS emulator page. tools/xfertest calls a board like a caller to measure transfers.