Board bring up for FujiNet Platform.IO code

The production version of the #FujiNet firmware is being written in Platform.IO. If you want to help work on it, you'll need to bring up this version of the code on your hardware.

Install USB to UART Driver

You may need to install the USB to UART driver for your operating system available from Silicon Labs

Install git

If you haven't already done so. Please install git, which is required to check out the code from the source code repository.

Linux

Debian/Ubuntu/Mint/etc.

apt-get install git-core

or

apt-get install build-essential

Which also adds a bunch of useful things.

For Ubuntu users

NOTE: You need to add yourself to the dialout group and reboot

sudo adduser $USER dialout
sudo reboot

Windows

Under Windows, git can simply be installed from here: https://git-scm.com/download/win

macOS

Installing XCode from the App Store will give you 'git'.

Install Visual Studio Code

Microsoft Visual Studio Code is used as the IDE for Platform.IO. You can get a copy of it for Windows, Linux, or Mac.

• Download a copy of Visual Studio Code for Windows, Mac, or Linux

Note for Linux users:

As I was testing these instructions for Linux, I found that I had to install the following packages after installing Visual Studio Code, due to only a limited Python environment being installed by default under Ubuntu based Linux distributions:

apt-get install python3-venv
apt-get install python3-distutils

Install Platform.IO

Once you've installed Visual Studio Code you will need to run Visual Studio Code and install the Platform.IO extension from the following Link:

• Install PlatformIO for Visual Studio Code

Restart Visual Studio Code

Let the resulting terminal window finish installing Platform.IO

Once the Reload Now button appears, press it.

Install support for your board

Once Platform.IO is installed, a new tab should appear with PIO Home, with icons down its left side. Select Platforms. You should then select Embedded. You should then select the ESP32 platform for #FujiNet:

• Espressif 32 - for ESP32 based boards

And press its install button.

As of November 2021, there are several bugs in the Espressif 32 IDF that need manual fixing until PlatformIO pulls in a newer version of ESP-IDF. These bugs affect the Espressif 32 PlatformIO version 3.3.2.

• Edit .platformio/packages/framework-espidf/components/mbedtls/esp_crt_bundle/cacrt_all.pem
  1. remove the EC-ACC certificate
• Edit .platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h
  • Add after the #includes:

#ifdef __cplusplus
extern "C" {
#endif

• and at the very bottom:

#ifdef __cplusplus
}
#endif

Clone the FujiNet repository

You should then press CTRL-` (the backtick), to open a terminal and move to where you want your repository to be. If you haven't created a space for projects, you should make one. e.g.

mkdir Projects
cd Projects

Anonymously cloning the repository

If you are only planning to test, you should then clone the repository with the following git command:

git clone https://github.com/FujiNetWIFI/fujinet-platformio.git

This command will download the project to a folder named fujinet-platformio in the current directory.

Using your GitHub account

If you intend to contribute to this code, you should have an account on github.com. It is easy enough to make one, and it's free.

You should then have an SSH public key associated with your account that matches the one used by Visual Studio Code. If there isn't one yet, you can run the following program to generate one:

ssh-keygen

And then view the contents of the file it generated:

cat ~/.ssh/id_rsa.pub

Copy the contents to the clipboard. Go to your account settings, select SSH Keys, and add the key you just copied into the clipboard there.

You can then check out the code with the following command:

git clone git@github.com:FujiNetWIFI/fujinet-platformio.git

This command will download the project to a folder named fujinet-platformio in the current directory.

Create a platformio.ini file from the sample before opening the project

Before opening the project, copy the file in the project folder you just cloned (fujinet-platformio) named platformio-sample.ini to platformio.ini. This file both tells the PlatformIO extension in Visual Studio Code that this is a PlatformIO project, and is the place you'll adjust settings for your particular hardware configuration (see below). For example:

cp platformio-sample.ini platformio.ini

Now open the project in Visual Studio Code by using the Open Folder option in the File menu and navigating to open the fujinet-platformio folder you cloned.

You should now see "FUJINET-PLATFORMIO" in the Explorer menu bar (click on the top-left icon that looks like a couple of stacked pages) with various folders including data, lib, and src.

Modify platformio.ini for your hardware configuration

Select the Explorer tab (upper-left-most icon) and open the platformio.ini file.

In the top [fujinet] section, uncomment the build_platform variable that targets the system you are building for.

Example:

[fujinet]
build_platform = BUILD_ATARI

In the second [platformio] section, change the default_envs setting to one appropriate for your FujiNet board:

• fujinet-v1: This includes the officially-produced FujiNet board. This should work for any other boards based on the ESP32 WROVER module with 8MB of PSRAM and 16MB of flash storage
• fujinet-v1-8mb: This is for custom ESP32 WROVER boards with 8MB PSRAM and 8MB of flash storage
• fujinet-v1-4mb: This is for custom ESP32 WROVER boards with 8MB PSRAM and 4MB of flash storage
• Note: we officially only support ESP32 WROVER with 8MB PSRAM and 16MB of flash storage

Example:

[platformio]
default_envs = fujinet-v1

In the [env] section, you need to set the communications port your board is connected to. This port is used for both loading the FujiNet firmware on the board and viewing its debugging output. The speeds defined in the sample configuration file should work in most configurations, but you'll very likely need to change the port number. upload_port and monitor_port are usually set to the same value, and upload_speed and monitor_speed are usually set to the same value.

Example:

[env]
upload_port = /dev/ttyUSB0
upload_speed = 921600
monitor_port = /dev/ttyUSB0
monitor_speed = 921600

If you'd like to change build settings, you should change them in the [env:] section. The main setting that is of interest here is the build_flags which makes certain changes when building the firmware code. Build flags of interest are:

• JTAG: Enables support for JTAG debugging.
• DEBUG_SPEED: Set's the FujiNet's debug output log speed. This should match the monitor_speed setting in the [env] section.
• BLUETOOTH_SUPPORT: Enables FujiNet's Bluetooth support. As the Bluetooth library is relatively large, disabling this can reduce required system resources.
• FN_HISPEED_INDEX: This is the "POKEY divisor" value FujiNet uses when communicating over the Atari SIO bus. The value is '6' by default, which is compatible with SpartDOS's high-speed mode. You can set this to '0' if you have an Atari OS that supports it.
• NO_BUTTONS: disables button activity within the code for custom boards that do not have them
• VERBOSE_xxx: Several VERBOSE flags that give more debugging information from FujiNet

Note that a semicolon before a value makes it disabled or use the default value.

This example has JTAG disabled but Bluetooth enabled and debug monitor speed set to 921,600 baud:

[env]
build_flags =
   ; -D JTAG
   -D BLUETOOTH_SUPPORT
   -D DEBUG_SPEED=921600

Attempt to compile

Select the Platform.IO tab (it has an "alien head" icon), and choose Build.

Upload the firmware to your ESP32 board

There are two blocks of data to upload to your board: the file system image and the firmware. The file system image consists of files that the firmware makes use of while operating (e.g. printer emulation fonts). These are stored in the project's data directory and don't change very often. The firmware is the actual code the board runs, and this changes with every new build.

Select the Upload File System Image task in the Platform.IO tab to upload the contents of the data directory.

Select the Upload task in the Platform.IO tab to upload the firmware to your board. This will also cause the firmware to be re-compiled if any changes have been made to any of the source code files.

If everything works, the FujiNet board should automatically reboot and start running the newly uploaded firmware image. You can use the Monitor option in the Platform.IO menu to view any debug logs the FujiNet generates as it operates.

Example debug output:

FujiNet 0.1.9ac27658 2020-07-20 02:55:52 Started @ 5
Starting heap: 4096180
PsramSize 3932108
himem phys 4456448
himem free 4456448
himem reserved 262144
SPIFFS mounted.
SD mounted.
Available heap: 4015444
Setup complete @ 542 (537ms)