The Complete Linux CLI Guide - FujiNetWIFI/fujinet-firmware GitHub Wiki

I wrote this document after having to setup and flash a FujiNet using a Macbook M1 (ARM) in a remote location- and failing. The VSC (VisualStudio) install of PIO and the ESP32 platform felt too slow and error-prone and I wanted to avoid any need for it. This all relies on the nice work from @fenrock which can handle config and build automation via the command line using the build.sh scripts he wrote.

Even though I wrote this for macOS I've since updated it while doing builds on Linux (Ubuntu) and updated this document.

This document should be suitable for any Linux style system (Linux, WSL) - just update for your local packages, environments and paths!

Interesting Bits

Building Firmware or FujiNet PC

As of 2024 the FujiNet-PC code base has been incorporated into the Firmware repo. FN-PC is the posix implementation of FN, it's used to run on desktop systems with emulation to provide a complete 8bit virual platform + FN without needed any other hardware. The build notes for FN-PC (as opposed to the Fujinet Firmware) are noted below. build.sh can build both systems.

The Complete Linux CLI Guide

  • v 1.4 - Aug 2024 - macOS nomenclature update
  • v 1.3 - Jun 2024 - updates with new macOS cli guide
  • v 1.2 - May 2024 - added notes for WSL build in W10
  • v 1.1 - Feb 2024
  • v 1.0 - Sep 2023

Setup Host

  • Have a UNIX style system. This has specific examples in Ubuntu but works for any UNIX style system as long as you adjust
  • If you have an older laptop sitting around-- download and copy Ubuntu LTS onto a USB stick
    • boot laptop and install full Ubuntu Desktop
  • If you have Windows 10/11 install WSL/WSL2 from the Microsoft Store; reboot your computer.

Configure Linux Environment

Often adding yourself to the dialout group is necessary for the proper perms for the USB port. Use the proper recent python release for the venv package below.

sudo apt update  && sudo apt upgrade

sudo adduser `whoami` dialout
newgrp dialout

sudo apt install git curl python3-venv cmake libmbedtls-dev libexpat1-dev -y

[reboot] (for groups- only needed to flash to usb)

Installing for WSL for Windows

Building FujiNet-PC

I had to install FujiNet-PC under Windows10 to run Altirra directly for some testing. I installed WSL for windows(10) and then needed to execute the following packages in order to get a successful build of FN-PC on the Windows system. These same packages should be installed on any Linux/Ubuntu system to build FujiNet-PC as well as the firmware.

My build command for FujiNet-PC was for the Atari version: build.sh -cp ATARI

[!tip] you can also build for Apple2 with: build.sh -cp APPLE

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install libpython3-dev
sudo apt-get install python3-venv
sudo apt-get install build-essential
sudo apt-get install cmake
sudo apt-get install libmbedtls-dev
sudo apt-get install pip
sudo pip install Jinja2

Then continue on....

Install PIO and Platform

With the Linux system setup and reasonably and minimally configured it's time to install the PIO build system. It's all python. PIO should always be installed in your home directory.

  • Pull down the PIO installer from PlatformIO 
    cd ~
curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py
  • run the installer 
    python3 ./get-platformio.py

[a bunch of things will install....]
  • Ensure the pio command is in your PATH 
    export PATH=$PATH:~/.platformio/penv/bin
  • Now use the PIO command to install our 'platform' i.e. the ESP32 chip which is on the FujiNet 
    pio platform install espressif32

[more things will install]

If you add this line to the end of your .bashrc you'll always have pio around- paste this into a terminal:

echo 'export PATH=$PATH:~/.platformio/penv/bin' >> ~/.bashrc

Clone FujiNet Firmware

Now we have PIO installed we should clone the FujiNet firmware repo.

Note about Cloning and Forking

If you are going to never add or modify the code and simply want to build it then you can just clone from the FujiNet repo directly. If you are interested in modifying or working on it you should fork the repo and then clone your fork locally. Work should be done in new branches on your fork and then pull requests used to contribute you code back to the main repo..

I keep all my github repos in a sub-folder called 'code' as you see below. Feel free to use whatever folder structure you are comfortable with.

NOTE: The PIO installation should always be from your home directory top-level, the FujiNet code repo can be anywhere.

mkdir code
cd code
git clone https://github.com/FujiNetWIFI/fujinet-firmware.git

cd fujinet-firmware/

Select your first Platform Target

This document will be using build.sh - a script in the home directory of the repo you just cloned. build.sh can be run without any parameters to give you a help response. It will be used to create the platform (Atari, Apple, Coco, etc..) files in such a way that they won't interfere with each other -- great if you are building more than one platform.

Note about platform.ini

Using the build.sh script you should not make a copy of the platformio.ini - let build.sh handle that with it's commands.

Select a platform

build.sh -s is the command to create the initial local PIO ini file for you to further modify.

The build.sh section for ini files is shown below:

fujinet-firmware board setup options:
   -s NAME  # Setup a new board from name, writes a new file 'platformio.local.ini'
   -i FILE  # use FILE as INI instead of platformio-generated.ini
   -l FILE  # use FILE to use instead of 'platform.local.ini'

We need to pick a board to setup, and then we can build firmware for that board.

At the end of the base output of the build.sh command it lists the boards it knows about:

Supported boards:

platformio-fujiapple-rev0.ini
platformio-fujimac-rev0.ini
platformio-fujinet-adam-v1.ini
platformio-fujinet-atari-v1.ini
platformio-fujinet-coco-devkitc.ini
platformio-fujinet-coco-lolin-d32-dw.ini
platformio-fujinet-cx16.ini
platformio-fujinet-heathkit-h89.ini
platformio-fujinet-iec-fujiapple.ini
platformio-fujinet-iec-lolin-d32.ini
platformio-fujinet-iec-nugget.ini
platformio-fujinet-lynx-prototype.ini
platformio-fujinet-rc2014spi-rev0.ini
platformio-fujinet-rs232-rev0.ini
platformio-fujinet-s100-v1-8mb.ini
platformio-fujinet-v1-8mb.ini

We can't use those strings as listed with the -s command- we need to drop the platformio- at the start and the .ini at the end. If we want to build for Atari then the proper command would look like:

$ ./build.sh -s fujinet-atari-v1

This produces a confirmation input to make sure you want to do this- type y and then RETURN...

[!tip] Refer to this guide to targets to aid selection of the target to use for your FujiNet.

WARNING! This will potentially overwrite any local changes in /home/myusername/code/fujinet-firmware/platformio.local.ini
Do you want to proceed? (y|N) y
/home/myusername/code/fujinet-firmware/platformio.local.ini file created with build_board = fujinet-atari-v1
Merged INI file created as '/home/myusername/code/fujinet-firmware/platformio-generated.ini'.

Now you can make your 'local' i.e. for your current system changes to the platformio.local.ini that was just created.

One of the changes you may need to make to that file is the /dev/tty device for your computer. It defaults to a straight Linux /dev/ttyUSB0 and if that is now how your FN device shows up on on your system you'll need to update it.

Find your FN USB Device

  • Mac Note - change the serial device in platformio.ini to something like: 
    /dev/cu.usbserial-XX (the XX may be unique to your system)
  • WSL - it's not easy to get the Windows USB port connected to your WSL1/2 subsystem. I made a video that goes over this: https://youtu.be/iofdXz_x8wc

Build Firmware

  • show help: 
    ./build.sh -h
  • just build - good for a test of everything we've installed so far: 
    ./build.sh -b
  • builds and flashes the firmware, the image (the webUI) and then monitors the USB port for debug output: 
    ./build.sh -fum
  • The FujiNet should show the flash updating, it should reboot and then try to find a wifi connection.
  • To build every single platform we can build for, check that it built ok and give you a summary in a file called build-results.txt in the root of the fujinet-firmware directory: 
    build.sh -a
    The output file looks something like this: 
    $ cat build-results.txt
Start Time: 2024-02-18 12:42:25 - ----- Starting Build the World for Fujinet


2024-02-18 12:45:14 - Built fujiapple-rev0
File 'firmware.bin' found------------------------------------------------
2024-02-18 12:47:17 - Built fujimac-rev0
File 'firmware.bin' found------------------------------------------------
2024-02-18 12:49:54 - Built fujinet-adam-v1
File 'firmware.bin' found------------------------------------------------
2024-02-18 12:52:56 - Built fujinet-atari-v1
File 'firmware.bin' found------------------------------------------------
2024-02-18 12:55:45 - Built fujinet-coco-lolin-d32-dw
File 'firmware.bin' found------------------------------------------------
2024-02-18 12:58:07 - Built fujinet-cx16
File 'firmware.bin' found------------------------------------------------
...
[more platforms]

Build FujiNet-PC

./build.sh -cp ATARI

[a bunch of cmake lines out.....]
[100%] Built target fujinet
[100%] Preparing dist directory
[100%] Built target dist
Built PC version in build/dist folder

cd build/dist
./run-fujinet

Starting FujiNet
14:46:46.292954 >
14:46:46.296802 >
14:46:46.296816 > --~--~--~--
14:46:46.296857 > FujiNet v1.3 2024-04-26 06:08:28 Started @ 27
14:46:46.296910 > Detected Hardware Version: fujinet-pc
14:46:46.296944 > SPIFFS mounted.
14:46:46.298056 > SD mounted (directory "SD").
14:46:46.298132 > fnConfig::load "fnconfig.ini"
...

Sample fnconfig.ini (for SD card)

If you cannot setup wifi via CONFIG manually you need to create a fnconfig.ini file on a SD card using your modern laptop and setup your local wifi credentials by hand.

A sample fnconfig is here to copy and use:

Sample-FNCONFIG.INI