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 contains 8 different compilations of the
same `tether` program, which runs on your PC (or Mac or Pi
or Linux).  Used the one correct program for your
operating system.  Below, we will just call it "tether".

    tether.linux-amd64.exe
        For most 64-bit Linux systems on Intel CPU.

    tether.linux-386.exe
        For older 32-bit Linux systems on Intel CPU.

    tether.linux-arm64.exe
        For Raspbery Pi with 64-bit OS.

    tether.linux-arm-7.exe
        For Raspbery Pi with 32-bit OS.

    tether.mac-amd64.exe
        For older MacOS with Intel CPU.

    tether.mac-arm64.exe
        For newer MacOS with Apple Silicon (M1, M2, M3, M4...)

    tether.win-386.exe
        For 32-bit Windows on Intel CPU

    tether.win-amd64.exe
        For 64-bit Windows on Intel CPU

*  Unzip the archive.

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

   2. tether

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

See the list of different tether programs for different
PC Operating Systems above.  When we say "tether",
use the correct one.  Or copy the correct one to the
name "tether".

*  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:
    (To see configurable flags, run `./mcp-bonobo-only -help`).

        ./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 don't really have to run this.  Instead,
    on the tether command (below), specify the global
    public MCP with `-mcp=pizga.net:2321`.)

    (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

    On windows, the device name will be something like COM8.
    There is a device manager in the Settings that can help
    you figure out what the device name is.  It is Okay to
    use trial and error.

    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)
    /R MUSIC     Run the MUSIC demo.

    /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.

    Unknown commands beginning with "/" crash
    the server.

    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


