pio 3 x howto - FujiNetWIFI/fujinet-firmware GitHub Wiki

Bringing Up the Software for FujiNet

Newer Version

There is a newer version of PIO that the project is using! Please read: pio 6 x howto

This document will remain here on the wiki for legacy purposes only.

This document will take you thru the steps needed to build, modify and deploy the FujiNet project onto the ESP32 system that is the heart of the FujiNet Hardware Device. Even if you are builing a raw devkit with an ESP32 dev board Board Bring Up Hardware or if you are using a retail FuijNet purcahsed from one of the many vendors selling them, you will have to build the same project and upload it to your device.

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. If you have a custom FujiNet device, some esp32 developer boards may not use the Silicon Labs CP2102 USB UART chip which is on official FujiNet hardware. Check with the board manufacturer and install the appropriate USB UART driver for your devkit board.

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

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 XCode via the command line with:

xcode-select --install

Brew

If you have brew installed you can install Visual Studio Code via brew:

brew install visual-studio-code

Brew also contains a better version of git for MacOS:

brew install 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[1]. You should then select Embedded[2]. You should then select the Espressif 32 ESP32 platform for #FujiNet.

On the pull-down ensure you choose version 3.4.0

Then click the install button[4].

Espressif 32 - for ESP32 based boards

You may need to quit and restart for the platforms to be loaded in the left-hand pane (Linux seems require a restart).

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 [email protected]:FujiNetWIFI/fujinet-platformio.git

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

Don't like SSH?

If you are not comfortable using SSH keys you can also use Personal Access Tokens to checkout and push code using HTTPS (not ssh).

Using Personal Access Tokens in GitHub Again, this is a requirement if you are adding and fixing code and making PR requests to help FujiNet. It is not required to simply pull the latest code, build it and flash your FujiNet.

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 and build_bus variable that targets the system you are building for. Also, uncomment the build_board variable that targets the physical hardware you are building for. Multiple build_board examples are provided in platformio-sample.ini but only one should be uncommented.

Setting USB Speeds

We were using 921600 for both upload and monitor speeds; however, we ran into a problem with one devit model that couldn't support that high rate, so dropped back to 460800. You can change the speeds back if your devkit works OK. Also have to change DEBUG_SPEED in build_flags to match the monitor_speed.

Unless you know exactly what you are doing, use 460800 as all speeds.

Example:

[fujinet]
; Espressif32 PlatformIO Version to use for building
esp32_platform_version = 3.4.0
;esp32_platform_version = 3.2.0 ; For Bluetooth support

; Uncomment the platform, bus and board type you are building for below
;build_platform = BUILD_ATARI
;build_bus      = SIO
;build_board    = fujinet-atari-v1       ; FujiNet for Atari v1.0 and up
;build_board    = fujinet-v1-8mb         ; Atari generic/custom with 8mb flash
;build_board    = fujinet-v1-4mb         ; Atari generic/custom with 4mb flash

;build_platform = BUILD_ADAM
;build_bus      = ADAMNET
;build_board    = fujinet-adam-v1       ; FujiNet for Coleco ADAM v1.0

;build_platform = BUILD_APPLE
;build_bus      = IWM
;build_board    = fujiapple-rev0         ; FujiApple Rev 0 Prototype
;build_board    = fujiapple-fujinetv1    ; FujiApple using Atari FujiNet v1.0

;build_platform = BUILD_CBM
;build_bus      = IEC
;build_board    = fujinet-cbm            ; Commodore IEC using Atari FujiNet

build_platform = BUILD_LYNX
build_bus      = comlynx
;build_board    = fujinet-lynx-prototype ; Lynx Prototype PCB
build_board    = fujinet-lynx-devkitc   ; Lynx with basic DEVKITC

;build_platform = BUILD_S100
;build_bus      = s100Bus
;build_board    = fujinet-v1-8mb         ; ESP32-DEVKITC-VE

In the above example, I've commented out the LYNX platform and the devkitc. Ensure only one platform is ever enabled at build time. Simply uncomment the platform, bus and board you want to build and ensure any others are commented out.

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

You can see what your local USB device is named by clicking on the Devices tab, all connected USB serial devices should be listed. If not ensure your USB cable is plugged in and then click the Refresh button.

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

The build_board variable chosen above selects a more specific [env] targeting specific hardware. There are additional build_flags in these sections that relate specifically to the platform selected. You may (un)comment build_flags in this section as needed BUT do NOT uncomment the PINMAP_XXXX line as this is needed to define which pins are used by the ESP32 (these are defined in include/pinmap.h).

Atari Example:

; FujiNet for Atari v1.0 and up (ESP32 WROVER 16MB Flash, 8MB PSRAM)
[env:fujinet-atari-v1]
platform = espressif32@${fujinet.esp32_platform_version}
board = fujinet-v1
build_type = debug
build_flags =
    ${env.build_flags}
    -D PINMAP_ATARIV1
    ;-D DEBUG_UDPSTREAM     ; enable UDP to display IN/OUT packets
    ;-D VERBOSE_SIO         ; Debug SIO
    ;-D VERBOSE_ATX         ; Debug ATX files
    ;-D FN_HISPEED_INDEX=0  ; Set SIO High Speed Index

Attempt to compile

Select the Platform.IO tab (it has an "alien head" icon).

Expand the project environment for the build_board you have chosen in platformio.ini. This will on-demand load required libraries/frameworks (this can take some time, the first time you do this).

Screenshot from 2022-07-11 18-10-55

Carefully Read this part

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

~~Edit .platformio/packages/framework-espidf/components/mbedtls/esp_crt_bundle/cacrt_all.pem~~
~~1. remove the EC-ACC certificate~~
2022-01-22 — The certificate appears to be fixed... "deprecating" this instruction until we're comfortable it's not an issue.
Edit .platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h
- NOTE: Under windows this file be usually be at %userprofile%\.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
```

If you are comfortable with a terminal, there are some UNIX commands that can make these changes for you. They are listed below for you to use.

This command will open the ifdef at the top of the dirent.h file:

gawk -i inplace '1;/#include\ <stdint.h>/{print "\n\n#ifdef __cplusplus\nextern \"C\" {\n#endif\n\n"}' ~/.platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h

This command will close the ifdef in the dirent.h file:

printf "\n\n\n#ifdef __cplusplus\n}\n#endif\n\n" >> ~/.platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h

You can verify the changes have been made to the file:

tail -n 10 ~/.platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h

head -n 30 ~/.platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h

Of course you can always just open up the file ~/.platformio/packages/framework-espidf/components/newlib/platform_include/sys/dirent.h in your favorite text editor and make the appropriate changes.

Return to the Platform.IO tab, and choose Build.

Screenshot from 2022-07-11 18-11-12

The TERMINAL section of Visual Studio Code will show the progress of the build. You know it's done right when you get the output:

[... bunch of text ...]

Retrieving maximum program size .pio/build/fujinet-v1/firmware.elf
Checking size .pio/build/fujinet-v1/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [          ]   1.1% (used 50036 bytes from 4521984 bytes)
Flash: [=         ]  14.4% (used 1363069 bytes from 9437184 bytes)
Building .pio/build/fujinet-v1/firmware.bin
esptool.py v3.1
Merged 2 ELF sections
================================================================= [SUCCESS] Took 104.31 seconds 

Environment    Status    Duration
-------------  --------  ------------
fujinet-v1     SUCCESS   00:01:44.307
================================================================== 1 succeeded in 00:01:44.307 

Terminal will be reused by tasks, press any key to close it.

If you see output that indicates error conditions you won't have a firmware.bin file to upload. Make the corrections to ensure that the build completes and you have a firmware.bin create. This will be used in the next steps to flash the fujinet with the new functionality.

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.

Upload Filesystem Image

After uploading the firmware, you may also need to Upload Filesystem Image. If your FujiNet has never had firmware installed or there are new changes to the CONFIG program and/or web interface, you must do this step. This will overwrite the SPIFFS filesystem data partition on the FujiNet which will wipe any settings (WiFi AP's, Host Slots, mounts, etc). A default set of Host Slots is installed. If you are using an SD card, the settings will be imported from it when the FujiNet boots after flashing.