nekotos-bonobo-quick-release (nebo) README
----------------------------------------------------

Tested on coco hardware:
  * coco2 (16K, 6809) with either CocoIOr or Bonobo
  * coco3 (512K, 6309) with either CocoIOr or Bonobo

(This release is for using the Bonobo card.
If you use the CocoIOr card, you don't need this;
Just boot with CocoIOr Axiom, go to page 39, and launch with "@".)

This release is compiled for Ubuntu 24.04 x86_64 GNU/Linux,
but this probably works with almost any x86_64 linux
in the last few years.  The Linux binaries are statically
linked, to maximum the chance of success.

*  Unzip the archive.

*  Three files are fundamental:
    
   1. bonobo.uf2   (a compiled C program for Raspberry Pi Pico 1)

   2. tether            (an x86_64 Linux static binary)

   3. mcp-bonobo-only   (an x86_64 Linux static binary)

*  Plus the *.game files are needed.

*  All other files are for your curiosity or debugging.

STEPS TO RUN:

0.  Plug the Copico Bonobo 2.4 card into your
    coco3, preferably without any MPI.  You can leave the
    coco3 powered off (or turn it on, it doesn't matter).

1.  Program the Pi Pico on the Bonobo board with the 
    "bonobo.uf2" file:

    Disconnect the USB cable for 5 seconds.
    Plug the USB into your Linux box.
    Wait 5 seconds.
    Type "df" and look for the final /media/ mount path,
       like /media/strick/RPI-RP2/
    Copy bonobo.uf2 into that mount:
       cp -vf bonobo.uf2 /media/strick/RPI-RP2/

    Leave the USB cable plugged in.

3.  In one shell, run this command:

        ./mcp-bonobo-only -games_dir=.

    If your .games files are in a different directory,
    name the path to it, instead of the final dot.

    You can add a flag for the default time zone of the
    clock game ( choose a slashed-location from this list
    https://data.iana.org/time-zones/tzdb-2021a/zone1970.tab ).
    Most users will override this by specifying a nearby airport
    on the tether command.
    
        ./mcp-bonobo-only -games_dir=. -zone=America/St_Johns

    (To see configurable flags, run `./mcp-bonobo-only -help`).

    Instead of mcp-bonobo-only, you may also run lemma-waiter
    from the frobio package.  Configure it with the same flags
    as mcp-bonobo-only.

4.  In another shell, run ./tether:
    To see configurable flags, run `./tether -help`.

        ./tether -handle=PAT -name="Patty" -airport=ORD

        (Note bug: keep -name short, 8 chars or less)

    You can wrap it in a "while loop" if you like:

        while sleep 1 ; do ./tether -handle=PAT -name="Patty" -airport=ORD ; done

    but it will take more than one ^C to kill it.

    To see other configurable flags, run `./tether -help`.
    If the Bonobo's Pi Pico does not show up as /dev/ttyACM0,
    configure it with a different device name like
        -wire=/dev/ttyACM1

    If the MCP is running on a different machine (say a server
    at a conference, or the global server), configure it like this:
        -mcp=pizga.net:2321

5.  Turn on your Coco3 on.
    If the screen is weird, reset it once.
    You should see NekotOS running.

6.  These are the temporary commands you can run:

    0   stop running a game
    L   conway's Life
    C   clock
    R   bogus demo saying Red    (chains to Green & Blue)
    F   very incomplete Forth interpreter, but you can try `23 42 * .` 
    S   spacewar  (multi-player game)
    G   cow-glider  (multi-player game, sort of)

    /J n    Join a room, for 40 <= n <= 99.
    /J      Leave the room.
    /W      Who is connected, and what Room they are in.

    To play a multiplayer game, the first person joins a room
    numbered 40 to 99.  Then other players join the room.
    Then the first player launches a game (like `S` or `G`).
    Also to play multiplayer games, you must all be using
    the same MCP server (mcp-bonobo-only or lemma-waiter).

    Hit BREAK to background the game, and BREAK to foreground it.
    (while it is backgrounded, you can use the 0 command to kill it,
    launch other games, or chat with people).

    If you type something other than the above commands,
    then you can chat with everyone.  Everyone sees everything
    everyone else types, both commands and just chats.

7.  If the ./tether command exits, run it again,
    and do the following step, too.

8.  If the LED blinks rapidly (10Hz), it's waiting for its Coco
    to be powered up or reset.  In the meantime,
    the Coco is HALTed, so it will appear frozen.

    If the LED on the Pi Pico blinks in Threes,
    that means it hit a fatal error.  Unplug the USB for 5 seconds
    and plug it back in.
       (now the LED flashes rapidly (10Hz) -- that means
       the Bonobo is HALTing your coco, and you must
       reset it.)
    Then hit RESET on your coco.
    And you're back to NekotOS.

KNOWN BUGS:

    If you are not the first person in the room,
    and you try to launch a game, the MCP will crash,
    and everything else will freeze.   Reset all
    machines, and restart the MCP.

    There is a memory corruption flake that strikes
    randomly and usually causes a PANIC, but can
    cause bad crashes with scary weird screens.

    The beaten path works pretty well, but trying
    weird stuff will find bugs.

REPOS:

  https://github.com/strickyak/nekotos

  https://github.com/strickyak/copico-bonobo

  https://github.com/strickyak/coco-shelf