Skip to content

Board Bring Up Software

Jump to bottom Edit New page
andy diller edited this page Jan 29, 2022 · 26 revisions

Bringing Up the Software for FujiNet

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

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

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:

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.

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

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

Attempt to compile

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

Expand the project environment (e.g. "fujinet-v1" to reveal the project tasks). This will on-demand load required libraries/frameworks (this can take some time, the first time you do this).

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

  1. 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.
  2. 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

Return to the Platform.IO tab, 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.

To recap:

  • Be in the correct git branch for the work you doing
  • Update code as required, saving when necessary
  • Build - will recomplie what is necessary given the changed files
  • Upload File System Image - use only if you have changed items in the data directory - like web or a CONFIG app for the platform. It's not necessary to do this step if you have just made changed to the firmware code.
  • Upload and Monitor - will upload the Firmware, reset the ESP32 and show debug output of the system in the VSC terminal area

Example debug output:

12:54:57.236 > --~--~--~--
12:54:57.236 > FujiNet 0.5.8d6b340f 2022-01-27 04:16:40 Started @ 5
12:54:57.237 > Starting heap: 4396479
12:54:57.272 > Detected Hardware Version: 1.0
12:54:57.423 > SPIFFS mounted.
12:54:57.505 > SD mounted.
12:54:57.505 > fnConfig::load
12:54:57.505 > Load fnconfig.ini from SD
12:54:57.505 > fopen = ok
12:54:57.509 > fnConfig::load read 631 bytes from config file
12:54:57.569 > SPIFFS Config Storage: Enabled
12:54:57.571 > fnConfig::load read 631 bytes from SPIFFS config file
12:54:57.679 > WIFI_EVENT_STA_START
12:54:57.679 > WiFi connect attempt to SSID "_irisindigo_"
12:54:57.681 > esp_wifi_connect returned 0
12:54:57.681 > 
12:54:57.681 > IWM FujiNet based on SmartportSD v1.15
12:54:57.683 > 
12:54:57.683 > IWM GPIO configured
12:54:57.683 > IWM timer started
12:54:57.683 > mounting serverResolving hostname "3.211.118.17"
12:54:57.683 > Resolved to address 3.211.118.17
12:54:57.683 > TNFS mount 3.211.118.17[3.211.118.17]:16384
12:54:57.683 > could not send data: 118Failed to send packet - retrying
12:54:58.425 > WIFI_EVENT_STA_CONNECTED
12:54:58.677 > could not send data: 118Failed to send packet - retrying
12:54:59.566 > IP_EVENT_STA_GOT_IP
12:54:59.566 > Obtained IP address: 10.0.0.151
12:54:59.566 > SNTP client start
12:54:59.568 > Starting web server on port 80
12:54:59.742 > TNFS mount successful. session: 0x18f8, version: 0x0102, min_retry: 1000ms
12:54:59.743 > vfs_tnfs_register "/tnfs0x3ffc367c" @ 0x3ffc367c = 0 "ESP_OK"
12:54:59.745 > 
12:54:59.745 > opening fileTNFS open file: "/APPLE/A2OSX.PO" (0x0001, 0x01b6)
12:54:59.850 > File opened, handle ID: 0, size: 33553920, pos: 0
12:54:59.850 > 
12:54:59.850 > Testing file tnfs_lseek currpos=0, pos=0, typ=1
12:55:00.383 > SNTP time sync event: Sat Jan 29, 12:55:00 2022 -0500
12:55:00.394 > 
12:55:00.394 > file open good
12:55:00.396 > Demo TNFS file open complete - remember to remove this codeAvailable heap: 4166023
12:55:05.386 > Setup complete @ 8154 (8149ms)

What is going where?

Loading builds into the ESP32. This diagram shows what parts are pushed into the ESP32

EOD

Copyright 2024 Contributors to the FujiNetWIFI project.

Join us on Discord: https://discord.gg/7MfFTvD

Clone this wiki locally