User Guide

Table of contents
  1. ROM Emulation
    1. Select the ROM to emulate
    2. Disable ROM Emulation
    3. Set the folder hosting the ROM files
    4. Set the URL of the ROM files
    5. Enable ROM delay / Ripper mode
  2. Floppies Emulation
    1. Pre-requisite: Hosting Floppy Images on microSD
    2. Select a .ST or .MSA Floppy Image to Emulate
    3. Read-Write Emulation for Floppy Images
    4. Create an empty writable floppy image
    5. Floppy image formats supported
  3. Hard Disk Emulation
    1. Introduction
    2. What is a GEMdrive
    3. Setting Up Hard Disk Emulation
    4. Features not supported and known issues
  4. Atari ST database of floppy images
    1. How to download and emulate a floppy image from the database
    2. Set the URL of the database and images files
  5. Real Time Clock (RTC)
    1. Enter into the RTC configuration menu
    2. Set the NTP parameters
    3. Set the UTC offset
    4. Change the RTC type
    5. Boot the emulator
  6. Boot a ROM image from the microSD card in ‘Rescue Mode’
    1. How to enable the Rescue Mode
    2. First boot after enabling the Rescue Mode
    3. Next boots
    4. How to disable the Rescue Mode
  7. Configurator Application
    1. Boot Mode Adjustments
    2. Count the number files in the folders of the microSD card
    3. Dark mode
    4. Latest release verification
    5. The STABLE and BETA release distribution workflows
  8. Enhanced Network Configuration
    1. Viewing Network Status
    2. Adjusting the authentication mode
      1. Configuring Authentication Mode
      2. Default Authentication Behavior
      3. Manual Configuration of Authentication Mode
      4. Troubleshooting Connectivity Issues
    3. Configuring the Country Code for Wi-Fi
      1. Default Configuration
      2. How to Set Your Country Code
      3. Troubleshooting and Performance Optimization
    4. Troubleshooting Wi-Fi Network Detection
      1. Adjusting Scan Frequency
      2. Considerations
      3. Finding the Right Balance
    5. Diagnosing Network Detection and Connectivity Issues
      1. Initial Connection and IP Address Acquisition
      2. Monitoring Network Status
      3. Adjusting the NETWORK_STATUS_SEC Parameter
      4. Finding the Optimal Balance
    6. Managing MAC Address Restrictions
      1. Understanding MAC Address Filtering
      2. Integrating the SidecarT with MAC Address Filtering
      3. Steps to Add the SidecarT MAC Address to Your Router
    7. Adjusting the File Download Timeout Setting
      1. Understanding the Default Timeout Duration
      2. Evaluating and Customizing the Timeout
      3. When to Modify the DOWNLOAD_TIMEOUT_SEC Parameter

ROM Emulation

v0.0.11

ROM Emulation is a pivotal feature of the SidecarT board, enabling the Atari ST to treat ROM files from a microSD card or an external web server as native ROM chips. This guide covers how use and set up the ROM Emulation.

Select the ROM to emulate

The SidecarT board can be configured to emulate a ROM file from a microSD card or an external web server. This section explains how to select the ROM to emulate in both cases.

  1. Enter into the Configurator mode by pressing the SELECT button more than one second. Now, power cycle your computer and the Configurator boot menu will be displayed. Press LEFT SHIFT to enter into the Configurator application, or wait 5 seconds to boot the Atari ST normally, open the Cartridge drive and run the SIDECART.TOS file.

  2. From the main menu, there are two options to emulate ROMS:

1. Emulate ROM image from microSD card
2. Emulate ROM image from Wi-Fi

For option 1, the SidecarT board needs a microSD card with the ROM files. The user can learn how to format a microSD card and transfer ROM files in the How to Format the microSD card section. For option 2, the SidecarT board needs to be connected to a Wi-Fi network. The user can learn how to connect the SidecarT board to a Wi-Fi network in the How to Connect to a Wi-Fi Network section.

The emulation of ROMs from Wi-Fi does not need a microSD card to work. And the emulation of ROMs from microSD card does not need to be connected to a Wi-Fi network to work.

  1. In the ROM selection menu, the user can select the ROM to emulate from the list of ROMs available. Simply press RETURN or ENTER to select the ROM to emulate, and the Atari ST will load and prepare the ROM to be used. The SidecarT board green led will blink an E in Morse code to indicate that the ROM is ready to be used.

  2. Gently reset or power cycle the Atari ST to use the ROM. The Atari ST will boot normally and will use the ROM as if it was a physical chip.

Disable ROM Emulation

Simply press again the SELECT button more than one second to enter into the Configurator mode and power cycle your computer.

Set the folder hosting the ROM files

The SidecarT board can be configured to use a folder in the microSD card to host the ROM files. This section explains how to configure the SidecarT board to use a folder in the microSD card.

  1. Preparation: Ensure you have a microSD card formatted to FAT16 or exFAT. For instructions, visit How to format the microSD card.

  2. Folder Creation: On the root directory of the microSD card, create a folder named roms. This will serve as the storage for the ROM files. By default, the SidecarT board will scan this directory for ROMs.

  3. ROM Transfers: Copy your ROM files into the roms folder. Supported formats are:
    • Pure binary (Raw binary data of the ROM)
    • STEEM format (Recognized if the file begins with four zeros or has a .STC extension)
  4. Activation:
    • Insert the microSD into the SidecarT board and power it up. The board will auto-recognize the microSD.
    • Access Configurator mode by pressing the SELECT button, navigate to the ROM selection, and choose your desired ROM. The Atari ST will access this ROM as if it was a physical chip.

If you prefer a different folder name instead of roms, you can modify the ROMS_FOLDER parameter. Details can be found in the Configuration Parameters section.

Set the URL of the ROM files

The SidecarT board can be configured to use a web server to host the ROM files. This section explains how to configure the SidecarT board to use a web server.

  1. URL Configuration: Point the SidecarT board to your web server’s ROM directory by setting the ROMS_YAML_URL parameter. The board expects a roms.json file at this location. To know more about creating this file, see Set up your own HTTP server for your ROMs.

  2. HTTPS Limitation:

The SidecarT board currently doesn’t support HTTPS. Ensure that your server uses HTTP only.

  1. Finalizing Setup: After updating the configuration, save your changes and reboot the board in Configurator mode.

Enable ROM delay / Ripper mode

The SidecarT board can be configured to add an extra step when accessing the ROM files. This is useful for example for ROMs tha require a post-activation after another software is loaded from a floppy or hard disk, like ripper-style ROMs did. This section explains how to configure the SidecarT board to enable the ROM delay.

  1. Toggling Delay: Access the Configurator application’s main menu and press the D key to enable/disable the ROM delay.

Pressing the D key switches the DELAY_ROM_EMULATION parameter between false and true. While direct editing is possible, using the D key is advised to prevent potential issues.

  1. Usage: When ROM delay is active, ROM emulation isn’t immediate post-power-up. Activation occurs after holding down the SELECT button for over a second.

Given the SELECT button’s dual function, you cannot access the Configurator mode using it directly. After enabling the ROM, press SELECT again to access the Configurator mode.

Floppies Emulation

beta-v0.0.16

The Floppies Emulation represents a significant enhancement to the SidecarT board. With this, the Atari ST can interface with floppy images on a microSD card as though they were actual floppy disks. Here’s how to get started with Floppies Emulation.

Pre-requisite: Hosting Floppy Images on microSD

To use the SidecarT board’s floppy emulation feature, the floppy images must reside in a specific directory on a FAT16 or exFAT formatted microSD card.

  1. MicroSD Preparation: The first requirement is a FAT16 or exFAT formatted microSD card. Instructions can be found in the How to format the microSD card guide.

If you’ve already set up ROM Emulation, your microSD is likely formatted appropriately, and you can bypass this step.

  1. Directory Structure: On the microSD’s root, create a floppies directory. This is where the board will scan for floppy images.

  2. Transferring Floppy Images: Move your .ST and .MSA formatted floppy images into the floppies directory. The board recognizes these files automatically.

  3. Initialization and Configuration:
    • Insert the microSD into the SidecarT board.
    • Power up the board; it should recognize the microSD card automatically.
    • Enter Configurator mode by pressing the SELECT button. Navigate to Emulate Floppy menu option.
    • A menu will display the following options:
      • Floppy [A]: Press A to select the floppy image to emulate in drive A from the list of available images in the folder.
      • [E]xecute boot sector: Press E to enable or disable the execution of the boot sector of the floppy image. Sometimes the boot sector contains an antivirus or copy protection that can interfere with the emulation, so it’s useful to disable it.
      • [X]BIOS interception: Press X to enable or disable the interception of the XBIOS calls to the floppy drive. Some software uses the XBIOS calls to access the floppy drive, so it’s useful to disable it specially in versions of TOS 1.00 and TOS 1.02.
      • Temp [M]emory type: Press M to select the memory type to use for the temporary memory used by the floppy emulation.The default is _dskbuf that uses the buffer created by the operating system. The other option is heap and uses the heap memory. This is an advanced parameter and I don’t recommend to change it unless you know what you are doing.
  4. Rebooting: There are three more options:
    • [S] - Start emulation: Press S to start the emulation of the floppy image in drive A in read-only mode.
    • [W] - Start emulation in read-write mode. Press W to start the emulation of the floppy image in drive A in read-write mode. This will create a copy of the floppy image with the .rw extension to avoid data loss, if it does not already exists.
    • [F] - Format a floppy image: Press F to format a floppy image in the drive A. This will create a new floppy image in the floppies folder with the .ST extension. The user can select the size of the floppy image to create and the volume name of the floppy. See the instructions below.

If floppies isn’t your desired directory name, it can be changed. Adjust the FLOPPIES_FOLDER parameter. Details are available in the Configuration Parameters section.

Select a .ST or .MSA Floppy Image to Emulate

Starting from v0.0.11 the Floppy Emulation supports .MSA files.

The steps to select the floppy image to emulate are the same for both read-only and read-write modes. The SidecarT will convert the .MSA files to .ST files on the fly.

Read-Write Emulation for Floppy Images

The SidecarT board’s ability to emulate floppy images in read-write mode is powerful. It lets the Atari ST write to these images, but this also poses risks.

To mitigate potential data loss, when a floppy image is chosen for read-write emulation, the SidecarT board creates a copy in the FLOPPIES_FOLDER. This duplicate has the .rw extension, and the Atari ST writes to it, leaving the original image untouched.

If a .rw duplicate already exists, the board will prioritize it over the original. It won’t spawn another .rw file, ensuring consistency between sessions.

It’s important to note that the SidecarT board won’t validate the integrity of .rw files. If such a file is corrupted, the Atari ST won’t be able to interface with it, either for reading or writing.

Create an empty writable floppy image

The SidecarT board can be configured to create an empty writable floppy image to create our own content or have a blank floppy image to copy files from the Atari ST.

After selecting the option [F] - Format a floppy image . Select this option and the SidecarT board will prompt for several parameters:

  • Size [1]-SS/DD (360KB), [2]-DS/DD (720KB), [3]-HD (1.44MB): Select the size of the floppy image to create.
  • Volume name (max 8 chars, dot, max 3 chars): The volume name of the floppy for the Atari ST computer. Can be empty.
  • Image name (max 255 chars): The name of the floppy image file stored in the microSD card. Cannot be empty.

Now the SidecarT will need a few seconds to create the empty floppy image. After that, the Atari ST will report to the user that the new image is ready to be used. The user can choose to start the image in read-only or read-write mode.

Floppy image formats supported

The default format supported by the SidecarT is the .ST format. Starting from version v0.0.11, SidecarT can also read the .MSA format, converting it to .ST format on the fly. Under the covers, everything is a .ST file.

A special mention to read-write images with the extions .rw. All .ST files are read-only files. The SidecarT board will create a copy of the .ST file with the .rw extension to emulate a writable floppy image.

Hard Disk Emulation

beta-v0.0.16

The Hard Disk Emulation feature is an experimental feature. It remains under active testing and development. If you opt to use it please backup your data regularly.

Introduction

The SidecarT board introduces a hard disk emulation feature for the Atari ST, offering a significant storage solution without the necessity for an actual hard disk. This guide details the setup and utilization of the Hard Disk Emulation feature.

Distinct from other methods, the SidecarT board uniquely facilitates hard disk emulation by integrating the Atari ST’s file system with that of a microSD card, managed by the RP2040 microcontroller. This method presents several benefits and drawbacks:

  • Advantages:
    • Unlimited hard disk size, allowing the use of the full capacity of the microSD card.
    • Not affected by the infamous Bad-DMA issue, as the SidecarT board doesn’t rely on the Atari ST’s DMA controller.
    • Compatibility across TOS versions 1.00 to 2.06.
    • Enables organizing files into folders on the microSD card, simulating multiple hard disks on a single card.
    • Facilitates easy file transfer between the microSD card and computers (PC/Mac/Linux).
    • Requires less or no memory compared to other emulation drivers.
  • Disadvantages:
    • Writing operations to the hard disk are slower than reading due to the slower protocol communication with the RP2040 during write operations.
    • Not all software is compatible, particularly those making direct hardware calls to the hard disk, as the SidecarT emulates hard disk functions by intercepting GEMDOS calls.
    • The emulation driver is less mature, potentially leading to bugs or issues during use.

Despite these challenges, the benefits of Hard Disk Emulation often surpass the drawbacks, providing a reliable storage solution. Moreover, with ongoing development, the SidecarT board is poised for further enhancements, promising an even more robust and user-friendly experience in the future.

What is a GEMdrive

The concept for the GEMdrive hard disk emulation originated with the GEMDOS component of the Hatari emulator, though it’s worth noting that there exists a GemDrive for the ACSI2STM project, which serves a different purpose. Initially, the plan was to borrow the GEMDOS implementation from Hatari and adapt it for use with the SidecarT board. However, this strategy proved unfeasible due to the Hatari emulator’s capability for extensive interaction with both the Atari ST’s internals and the host computer—capabilities that the SidecarT board, as a peripheral, cannot match due to its need to adhere to the Atari ST’s hardware constraints. The GEMDOS code from Hatari was ultimately deemed too intricate and too intertwined with the emulator itself for direct application in the SidecarT environment. Nevertheless, the exploration of Hatari’s GEMDOS code was highly informative, leading to the development of a bespoke GEMdrive code specifically tailored for the SidecarT board.

The original GEMDOS driver allowed for the mounting of a Windows/OSX/Linux filesystem as an Atari ST disk drive, a functionality mirrored by the GEMdrive through its use of the microSD card filesystem, FatFS. While some advanced users may view this solution as excessive, it represents the sole method by which to provide substantial storage capacity to the Atari ST. More significantly, it marks a crucial initial step towards realizing a network filesystem for the Atari ST.

Setting Up Hard Disk Emulation

To activate the hard disk emulation feature on the SidecarT board, you must first ensure that the emulation files are properly placed within a designated directory on a FAT16 or exFAT formatted microSD card. While hd is the default directory name for these files, it can be customized to suit your preferences.

  1. MicroSD Card Setup: Skip this step if your microSD card is already set up with ROMs and/or floppy images. Otherwise, start by formatting the microSD card to FAT16 or exFAT. Detailed formatting instructions are available in the microSD Card Formatting Guide.

  2. Creating the Directory: In the root directory of the microSD card, create a folder named hd. This folder will be scanned by the board to locate your emulated hard disk files.

  3. File Transfer: Transfer files and folders from your PC/Mac/Linux computer to the hd folder on the microSD card. These will be recognized by the SidecarT board as part of the emulated hard disk. Additionally, you can manage file transfers between the emulated hard disk and other hard disk drivers.

  4. Initialization and Setup:
    • Insert the prepared microSD card into the SidecarT board.
    • Turn on the board. It will automatically detect the microSD card.
    • Access the Configurator by pressing the SELECT button and navigate to the Emulate Hard Disk option.
    • Within this menu, you will find several settings:
      • [D]rive: Hit D to choose the drive letter for emulation, ranging from C to Z. Select a unique letter if using multiple hard disk drivers.
      • Temp [M]emory Type: Press M to pick the type of temporary memory for emulation. The default _dskbuf utilizes the operating system’s buffer, while heap opts for heap memory. This setting is advanced and should only be altered with caution.
      • [R]TC Enabled: Toggle the Real Time Clock (RTC) by pressing R. Enabling RTC ensures accurate date and time for files and the Atari ST computer.
      • [T]imeout (Seconds): Set the wait time for network and NTP server synchronization, with a default of 45 seconds.
  5. Starting the Emulation:
    • Additional options include:
      • [S] - Start Emulation: Press S to commence hard disk emulation using the chosen drive letter.

Note: If you prefer a directory name other than hd, you can modify the GEMDRIVE_DRIVE parameter in the configuration settings. For more information, refer to the Configuration Parameters section.

Features not supported and known issues

If you can’t enter into Configurator, please read this

The SidecarT board’s hard disk emulation feature does not support the following functionalities in verision v0.0.16:

  • Volume Name: It does not support volume names for the hard disk emulation. The Atari ST will not display the volume name of the hard disk.

  • Pipes: The current version does not support pipes. The Atari ST will not be able to use pipes with the hard disk emulation.

  • Support for MegaSTE in 16Mhz + Cache enabled: This configuration is not supported in v0.0.16, but it will eventually be supported in v0.0.17.

  • AUTO folder shuffle: The GEMDRIVE can read from the AUTO folder, but the order of the files is lexical. This can be a problem for some software that needs to be executed in a specific order. This will be fixed in future versions.

All the features are planned for future releases.

The lastest adapted games for hard disk by Peter Putnik and others does support the GEMdrive emulation. You can find them in the Atari ST Adapted Games site. Most of the games with HAGA and HAGE support does work with the GEMdrive emulation with TOS ranging from 1.00 to 2.06 and 1MB of RAM.

Atari ST database of floppy images

beta-v0.0.16

The SidecarT board can read a database of floppy images hosted on a remote web server. This feature is built on top of the Floppies Emulation one. This is an out of the box feature that doesn’t require any additional configuration besides the one explained above for the Floppies Emulation.

How to download and emulate a floppy image from the database

This section explains how to select the floppy image to emulate from the database:

  1. Enter into the Configurator mode by pressing the SELECT button more than one second. Now, power cycle your computer and the Configurator boot menu will be displayed. Press LEFT SHIFT to enter into the Configurator application, or wait 5 seconds to boot the Atari ST normally, open the Cartridge drive and run the SIDECART.TOS file.

  2. From the main menu, select the option

5. Download from the Floppy Images database

  1. In the menu, there is a bar with the alphabet and numbers. Selecting the letter or number will display the list of applications starting with that letter in the name.

  2. The user can now select the application to download pressing RETURN or ENTER. Now, the SidecarT board will find the floppy image in the database that contains the application and download it to the storage folder for floppy images.

  3. After the download is finished, the Atari ST will redirect the user to the Floppy Emulation menu to select how to use the floppy image.

  4. From the menu the user can reset the computer. The Atari ST will boot normally and will use the floppy image as if it was a physical floppy disk.

Set the URL of the database and images files

For avanced users only.

The SidecarT board can be configured to use a web server to host both the database and images files. It’s not necessary to have both in the same server.

  1. URL Configuration: Point the SidecarT board to your web server’s Atari ST database by setting the FLOPPY_DB_URL parameter. The board expects a folder named db and a file for each alphabet letter and number. Each of these files in Comma Separated Values (CSV) format contains the list of disk files urls. See Set up your own HTTP server for your Atari ST database.

  2. HTTPS Limitation:

The SidecarT board currently doesn’t support HTTPS. Ensure that your server uses HTTP only.

  1. Finalizing Setup: After updating the configuration, save your changes and reboot the board in Configurator mode.

Real Time Clock (RTC)

beta-v0.0.16

Starting from the version v0.0.11 of the firmware, the SidecarT board can be configured to be a Real Time Clock (RTC) for the Atari ST. This section explains how to configure the SidecarT board to be a RTC.

Enter into the RTC configuration menu

The menu to configure the RTC is available in the Configurator application. To access it, press the 6 option in the main menu. The following menu will be displayed:

NTP Server: <<value in the RTC_NTP_SERVER_HOST and RTC_NTP_SERVER_PORT configuration parameter>>
RTC Type: <<value in the RTC_TYPE configuration parameter>>
RTC UTC Offset: <<value inthe RTC_UTC_OFFSET>>

Options:
[1] - Set SIDECART RTC with a custom firmware
[2] - Set DALLAS 1216 RTC with cartridge emulation
[U] - Change UTC offset
[H] - Change NTP server host
[P] - Change NTP server port

[B] - Boot emulator

Press an option key or [ESC] to exit:

Set the NTP parameters

The user can change the NTP server host and port by pressing the H and P keys respectively. The default values are pool.ntp.org for the host and 123 for the port, which are the most common values and should work for most users.

Set the UTC offset

The user can change the UTC offset by pressing the U key. The default value is 0, which means the UTC offset is null. The NTP time returned by any server does not know about timezones, so the SidecarT board needs to know the UTC offset to be able to convert the UTC time to the local time. The UTC offset is expressed in positive or negative hours.

Also note that the Atari ST does not know about timezones either, so the RTC time will be the local time of the Atari ST.

Change the RTC type

For the version v0.0.11, there are two RTC types available: SIDECART and DALLAS. The user can change the RTC type by pressing the 1 or 2 keys. The default value is SIDECART. Each type has different characteristics:

  • SIDECART: This is the default RTC type. To set the date and time it uses a small cartridge firmware at boot time that sets the date and time in the Atari ST computer. This firmware is executed at boot time as an executable cartridge and does not impact in the overall performance or memory usage of the system.

  • DALLAS: This RTC type emulates a DALLAS 1216 RTC integrated chip. To set the date and time the user must use a program that reads the values provided by the DALLAS 1216 emulator and sets the date and time in the Atari ST computer. There are several programs that can do this, but I strongly recommend the tools created by Troed Sångberg.

Both solutions workaround the Y2K problem, or any problem with dates this century. So far.

Boot the emulator

To Boot the emulator, press the B key. The SidecarT board will reboot and depending on the RTC type chosen the flow will differ:

  • SIDECART: The SidecarT board will boot the cartridge firmware that will set the date and time in the Atari ST computer. After that, the Atari ST will boot normally. The firmware will report how the process goes in the screen. This is important because the RP2040 must query the NTP server to get the time and set it in the Atari ST computer, and this can take several seconds. The Atari ST will not boot until the date and time are set, or fails.

  • DALLAS: The Atari ST will boot normally. As explained above, the user must use a program that reads the values provided by the DALLAS 1216 emulator and sets the date and time in the Atari ST computer. Please keep in mind that DALLAS RTC emulation will only provide a valid date and time once the RP2040 obtains a valid date and time from the NTP server.

The SidecarT will not return a valid date and time until it obtains a valid date and time from the NTP server. In the SIDECART RTC type, the Atari ST will not boot until the date and time are set, or fails. In the DALLAS RTC type, the Atari ST will boot normally, but the date and time will be invalid until the user sets them with a program.

Boot a ROM image from the microSD card in ‘Rescue Mode’

v0.0.11

The SidecarT can be a very helpful device to troubleshoot damaged computers. A good use case is bypass the configurator and let the SidecarT to run a “default ROM” when plugged. This new feature is called “Rescue Mode”, and it will boot a ROM image from the microSD card when the SidecarT is plugged in the Atari ST without interacting with the configurator.

How to enable the Rescue Mode

To enable the Rescue Mode, the user must create a file named .romrescue in the root of the microSD card. The content of the file must be the name of the ROM image to boot as found in the ROMS_FOLDER (roms by default) configuration parameter. It’s important to note that the user does not have to include the full path, just the name of the ROM image.

For example, if the user wants to boot a diagnostic ROM image named ST Test v4.4.img located in the roms folder, the content of the .romrescue file must be ST Test v4.4.img.

First boot after enabling the Rescue Mode

After saving the .romrescue file in the microSD card, insert the microSD card in the SidecarT and power on the Atari ST. Now, press the SELECT button more than one second to enter into the Configurator mode. Now the SidecarT will automatically read the .romrescue file and will save its content in the FLASH memory of the RP2040.

Next boots

After that, the SidecarT will reboot in ROM_EMULATION mode and the Atari ST will boot the ROM image specified.

How to disable the Rescue Mode

To disable the Rescue Mode, the user must delete the .romrescue file from the microSD card, or rename it. After that, if the user press the SELECT button for more than one second, the SidecarT will start in the Configurator mode as usual.

Configurator Application

beta-v0.0.16

The Configurator application serves as the central interface for the SidecarT board’s configurations. It’s alternately known as the firmware or the firmware application. This guide will walk you through the nuances of the Configurator application.

Boot Mode Adjustments

Upon the initial power-up of the SidecarT board, or when the SELECT button is held for over 1 second, the Configurator is invoked. This application resides in the Cartridge drive, which is visible upon starting the Atari ST.

The behavior when pressing SELECT for over 1 second is configurable. The SidecarT board can either:

  1. Swiftly transition to the Configurator mode, or
  2. Delay this transition until the Atari ST’s next full power cycle (not just a reset).

This behavior is determined by the SAFE_CONFIG_REBOOT parameter.

Immediately transitioning can be jarring for ongoing Atari ST applications. Especially for applications or drivers overseeing other storage devices, this abrupt switch can lead to compatibility concerns. As a preventive measure, the SidecarT board can be set to defer this transition until the subsequent power cycle.

By default, SAFE_CONFIG_REBOOT is set to true. This means the SidecarT will hold off until the next power cycle before transitioning to Configurator mode. Altering this behavior involves tweaking the SAFE_CONFIG_REBOOT parameter. Further insights can be found in the Configuration Parameters section.

There are valid scenarios where setting SAFE_CONFIG_REBOOT to false makes sense. For instance, developers frequently adjusting the SidecarT configuration might find repeatedly waiting for a power cycle tedious. However, exercise this option judiciously.

Count the number files in the folders of the microSD card

The SidecarT board can be configured to count the number of files in the folders of the microSD card. This feature is useful to know how many ROMs or floppy images and files in the hard disk folders are available. This feature is configured by default, but the user can disable it if the number of files is too big and the SidecarT board is slow to boot.

To disable this feature, the user must set the FILE_COUNT_ENABLED parameter to false. The user can learn more about this parameter in the Configuration Parameters section. To return to the default behavior, the user must set the FILE_COUNT_ENABLED parameter to true.

Dark mode

The SidecarT board can be configured to use a dark mode in the Configurator application for medium resolution mode. This feature is useful for old CRT monitors that can have problems with the white background of the Configurator application. By default the dark mode is disabled, but the user can enable it by setting the CONFIGURATOR_DARK parameter to true. The user can learn more about this parameter in the Configuration Parameters section. To return to the default behavior, the user must set the CONFIGURATOR_DARK parameter to false.

Latest release verification

The SidecarT board can be configured to check for the latest release of the firmware available. When the board is connected to the internet, it will check for the latest release and display a blinking exclamation mark at the right side of the current version number at the top bar of the Configurator application. This section explains how to configure the SidecarT board to check for the latest release.

You have to be connected to the internet to check for the latest release.

  1. URL Configuration: The parameter LATEST_RELEASE_URL has to point to a file hosted on a web server. This file has to contain the latest release version number in the first line. The SidecarT board will check this file and compare the version number with the current version number. If the version number is different, the SidecarT board will display a blinking exclamation mark as explained above.

  2. HTTPS Limitation:

The SidecarT board currently doesn’t support HTTPS. Ensure that your server uses HTTP only.

The STABLE and BETA release distribution workflows

The SidecarT board Latest release verification can be configured to check for new releases of type STABLE or BETA. With the growing user base of SidecarT, the need for extensive and stability-focused testing is becoming increasingly important. To address this, we propose introducing two distinct release workflows. This approach aims to balance the needs of our diverse user community, ranging from makers to those seeking more stable and reliable software.

  1. BETA Release Workflow: This caters to users who are interested in testing the latest features and providing valuable feedback. It allows us to incorporate user experiences into development, ensuring that the software meets a wide range of needs and use cases.

  2. STABLE Release Workflow: Aimed at users who prioritize stability and reliability. This workflow focuses on delivering a polished and thoroughly tested version of the software, thereby reducing support queries and enhancing user satisfaction.

This is controlled through the LATEST_RELEASE_URL parameter in the configuration.

If LATEST_RELEASE_URL points to http://atarist./version.txt, users will be notified about the availability of a new STABLE (or latest) release.

If LATEST_RELEASE_URL points to http://atarist./beta.txt, users will be alerted when a new BETA release is available.

In both cases, the SidecarT board will check for the latest release and display a blinking exclamation mark at the right side of the current version number at the top bar of the Configurator application.

To download the STABLE (latest) or BETA release, navigate to the Download page and download the appropriate file. Then, follow the Update the firmware guide.

Enhanced Network Configuration

beta-v0.0.16

As of Beta release v0.0.15, the SidecarT board introduces the capability to adjust a range of network settings, designed to aid in diagnosing and resolving Wi-Fi and other network-related challenges. These settings are accessible through the C. SidecarT Configuration menu.

Viewing Network Status

To get an overview of the current network configuration and status, navigate to the W. Wi-Fi Configuration menu. Here, you will find detailed information that is essential for identifying and addressing network issues:

  • SSID: The name of the Wi-Fi network (SSID), which can be set using the WIFI_SSID parameter.
  • Auth Mode: Specifies the authentication mode used by the Wi-Fi network, adjustable via the WIFI_AUTH parameter.
  • Scan Interval: Defines the duration, in seconds, between consecutive Wi-Fi network scans. This setting helps in refreshing the network list periodically, based on the WIFI_SCAN_SECONDS parameter.
  • Country: Sets the country code for the Wi-Fi network. Initially configured to a default value that accommodates a broad range of networks globally, it may need adjustment to match the ISO-3166-alpha-2 code of your specific country for optimal performance. This is modifiable through the WIFI_COUNTRY parameter.
  • Status: Provides real-time insights into the connection’s current state.
  • IP Address: Displays the SidecarT board’s IP address within the Wi-Fi network.
  • Gateway: Shows the gateway’s IP address for the Wi-Fi network.
  • Netmask: Indicates the network’s subnet mask.
  • DNS Server: Reveals the DNS server’s IP address used by the Wi-Fi network.
  • MAC Address: Lists the MAC address of the SidecarT board within the network.
  • Check Interval: The frequency, in seconds, at which the SidecarT board reviews the network’s status, controlled by the NETWORK_STATUS_SEC parameter.
  • File Download Timeout: The maximum wait time, in seconds, for downloading a file over the Wi-Fi network, set using the DOWNLOAD_TIMEOUT_SEC parameter.

These configurable options empower users to fine-tune their network settings, facilitating improved connectivity and troubleshooting capabilities.

Adjusting the authentication mode

Configuring Authentication Mode

The SidecarT board employs a smart mechanism to determine the Wi-Fi network’s authentication mode, enhancing the ease of connectivity. This section guides you through adjusting the authentication settings to ensure a successful network connection.

Default Authentication Behavior

Upon attempting to connect to a Wi-Fi network, the SidecarT board initially endeavors to intelligently ascertain the network’s authentication mode under the following conditions:

  • If the WIFI_PASSWORD parameter is populated (i.e., the string length is greater than 0) or if a .wifipass file is present at the root of the microSD card, the board attempts to automatically identify the correct authentication mode for the specified SSID.

  • Conversely, if the WIFI_PASSWORD parameter is left blank and there is no .wifipass file found, the board defaults to using the OPEN authentication mode. This mode is denoted by the value 0 in the WIFI_AUTH parameter, indicating no encryption or password protection.

Manual Configuration of Authentication Mode

There may be instances where automatic detection does not yield the correct authentication mode, or you might prefer to specify a particular mode for your network connection. For such scenarios, you can manually set the WIFI_AUTH parameter to one of the predefined values to enforce a specific authentication protocol:

  • 0: OPEN (no encryption)
  • 1, 2: WPA TKIP PSK (Temporal Key Integrity Protocol with Pre-Shared Key)
  • 3, 4, 5: WPA2 AES PSK (Wi-Fi Protected Access II with Advanced Encryption Standard and Pre-Shared Key)
  • 6, 7, 8: WPA/WPA2 MIXED PSK (Mixed mode supporting both WPA and WPA2 standards)

Troubleshooting Connectivity Issues

Should you encounter difficulties in establishing a connection or receiving a valid IP address from the DHCP server, it is recommended to experiment with the different WIFI_AUTH values. Switching between authentication modes can help identify a compatible setting that facilitates a successful connection to the network.

By understanding and leveraging the WIFI_AUTH parameter, you can fine-tune the SidecarT board’s network authentication to match the security requirements of your Wi-Fi network, ensuring a stable and secure connection.

Configuring the Country Code for Wi-Fi

The SidecarT board facilitates precise control over Wi-Fi connectivity through the WIFI_COUNTRY parameter. This setting allows users to define the country code corresponding to their Wi-Fi network, optimizing performance by aligning with local network regulations and bands.

Default Configuration

By default, the WIFI_COUNTRY parameter is preset to XX, activating a Worldwide mode. This mode is designed to ensure broad compatibility across global networks. Nonetheless, for enhanced connectivity and to leverage region-specific network optimizations, adjusting this parameter to reflect your location’s ISO-3166-alpha-2 code is advisable.

How to Set Your Country Code

To tailor the WIFI_COUNTRY parameter to your locale, reference the ISO-3166-alpha-2 code corresponding to your country. Below is a markdown-formatted list of countries with their respective codes:

  • Argentina: AR
  • Australia: AU
  • Austria: AT
  • Belgium: BE
  • Brazil: BR
  • Canada: CA
  • Chile: CL
  • China: CN
  • Colombia: CO
  • Czech Republic: CZ
  • Denmark: DK
  • Estonia: EE
  • Finland: FI
  • France: FR
  • Germany: DE
  • Greece: GR
  • Hong Kong: HK
  • Hungary: HU
  • Iceland: IS
  • India: IN
  • Israel: IL
  • Italy: IT
  • Japan: JP
  • Kenya: KE
  • Latvia: LV
  • Liechtenstein: LI
  • Lithuania: LT
  • Luxembourg: LU
  • Malaysia: MY
  • Malta: MT
  • Mexico: MX
  • Netherlands: NL
  • New Zealand: NZ
  • Nigeria: NG
  • Norway: NO
  • Peru: PE
  • Philippines: PH
  • Poland: PL
  • Portugal: PT
  • Singapore: SG
  • Slovakia: SK
  • Slovenia: SI
  • South Africa: ZA
  • South Korea: KR
  • Spain: ES
  • Sweden: SE
  • Switzerland: CH
  • Taiwan: TW
  • Thailand: TH
  • Turkey: TR
  • United Kingdom: GB
  • United States: US
  • Worldwide: XX

Note: If your country is not listed, the Worldwide mode (XX) is recommended to ensure compatibility across various global networks.

Troubleshooting and Performance Optimization

Experimenting with different WIFI_COUNTRY settings may be necessary to resolve connectivity issues or optimize network performance. Although setting the WIFI_COUNTRY parameter to your country’s ISO-3166-alpha-2 code is generally recommended, varying this setting could yield improvements in connection stability, speed, or latency. Adjusting the country code offers a strategic approach to fine-tuning Wi-Fi performance for your specific environment.

Troubleshooting Wi-Fi Network Detection

Detecting Wi-Fi networks with the SidecarT board can sometimes be challenging due to various external factors such as environmental conditions, network congestion, and signal interference. If you’re experiencing issues with finding your Wi-Fi network, adjusting the WIFI_SCAN_SECONDS parameter may improve the situation.

Adjusting Scan Frequency

The WIFI_SCAN_SECONDS parameter controls how often the SidecarT board scans for available Wi-Fi networks. Decreasing this value causes the board to search for networks more frequently, which might increase the chances of successfully detecting your Wi-Fi network.

Considerations

While lowering the WIFI_SCAN_SECONDS value can aid in detecting Wi-Fi networks more readily, it’s important to be mindful of potential drawbacks:

  • Resource Consumption: More frequent scanning consumes additional computational resources. This heightened activity can impact the performance of the Configurator application, potentially leading to a less responsive user experience.

Finding the Right Balance

Finding the optimal setting for WIFI_SCAN_SECONDS involves balancing the need for effective network detection with maintaining good system performance.

Diagnosing Network Detection and Connectivity Issues

Ensuring seamless network detection and connection is critical for the optimal operation of the SidecarT board. This process involves establishing a Wi-Fi connection followed by acquiring an IP address from the DHCP server. Understanding and managing these steps can significantly enhance your network interaction experience.

Initial Connection and IP Address Acquisition

Once a Wi-Fi connection is successfully established, the SidecarT board seeks to obtain an IP address from the DHCP server. A failure to secure a valid IP address results in the absence of displayed network details, indicating an incomplete connection.

Monitoring Network Status

The frequency at which the SidecarT board checks the network status is determined by the NETWORK_STATUS_SEC parameter. This check occurs periodically:

  • Without a Valid IP Address: If the board hasn’t received a valid IP from the DHCP server, it performs status checks every NETWORK_STATUS_SEC seconds to attempt to resolve this issue.
  • With a Valid IP Address: Once a valid IP is obtained, the board continues to monitor the network at the same interval, ensuring the connection remains active.

Certain DHCP servers may exhibit delays in IP allocation. To counteract potential wait times, you might consider reducing the NETWORK_STATUS_SEC value, potentially to as low as 3 seconds, to prompt more frequent attempts at acquiring an IP address.

Adjusting the NETWORK_STATUS_SEC Parameter

Modifying the NETWORK_STATUS_SEC parameter to a lower figure can lead to increased CPU usage and additional network traffic, as the board will more aggressively seek to establish or maintain its network connection. It’s advisable to approach adjustments to this parameter with caution. The default setting of 10 seconds is generally sufficient for obtaining a valid IP address in most scenarios without unduly taxing system resources.

Finding the Optimal Balance

Adjusting network settings on the SidecarT board, especially the NETWORK_STATUS_SEC parameter, requires a careful balance between ensuring quick network connectivity and maintaining overall system performance. Experimenting with different settings can help identify the most effective configuration for your specific network environment and usage requirements.

Managing MAC Address Restrictions

The MAC address serves as a fixed, unique identifier for the SidecarT board’s network interface, essential for communication within the physical network segment. It’s important to note that the MAC address of the SidecarT board cannot be altered.

Understanding MAC Address Filtering

Many networks implement MAC address filtering as a security measure, controlling access by explicitly permitting or blocking devices based on their MAC addresses. This approach ensures only recognized devices can connect to the network.

Integrating the SidecarT with MAC Address Filtering

Should your network employ MAC address filtering, you must register the SidecarT board’s MAC address with your router to grant it network access. You can find the MAC address listed within the W. Wi-Fi Configuration menu of the SidecarT board.

Steps to Add the SidecarT MAC Address to Your Router

  1. Access the W. Wi-Fi Configuration menu on your SidecarT board to locate its MAC address.
  2. Log into your router’s administration interface. This typically involves entering the router’s IP address in a web browser and signing in with your credentials.
  3. Navigate to the MAC address filtering section. The exact location of this setting can vary depending on your router’s brand and firmware.
  4. Enter the SidecarT board’s MAC address into the list of allowed devices. You may need to select an option to “Add” or “Allow” a new device.
  5. Save your changes and, if necessary, restart the router for the new settings to take effect.

By ensuring the SidecarT board’s MAC address is recognized and permitted by your network’s filtering rules, you’ll facilitate a smooth connection process, allowing the board to communicate effectively with other devices on the network.

Adjusting the File Download Timeout Setting

The DOWNLOAD_TIMEOUT_SEC parameter on the SidecarT board plays a critical role in defining the time limit for file downloads over the Wi-Fi network. This setting is crucial for efficiently managing the retrieval of ROM and floppy images, ensuring that these resources are accessed in a timely manner.

Understanding the Default Timeout Duration

Initially, the default timeout was set at 30 seconds. Based on user feedback concerning download times, this has been extended to 60 seconds. This adjustment aims to offer a more accommodating window for file downloads, catering to varying network speeds and file sizes.

Evaluating and Customizing the Timeout

Given that the files targeted for download typically do not exceed 1MB, the default 60-second timeout should suffice for the majority of use cases. Nonetheless, the primary bottleneck in the download process is not the file size but rather the latency involved in establishing a connection to the server, initiating the download, and processing each segment of the file. The RP2040 microcontroller, with its limited memory and computational capabilities, processes downloads more slowly compared to standard computers, making latency a more significant factor than bandwidth.

When to Modify the DOWNLOAD_TIMEOUT_SEC Parameter

  • Increasing the Timeout: If you experience difficulties in completing downloads within the 60-second window, it may be necessary to extend the DOWNLOAD_TIMEOUT_SEC duration. This adjustment can accommodate slower server response times or any network latency issues, ensuring that downloads can complete successfully.

  • Decreasing the Timeout: Conversely, if downloads are consistently finishing well before the 60-second mark, you might consider reducing the timeout setting. This can streamline the network interaction process, preventing unnecessary delays in cases where downloads are completed more swiftly.

Adjusting the DOWNLOAD_TIMEOUT_SEC parameter allows you to tailor the download experience to your specific network conditions and the performance of the SidecarT board. Experimenting with different settings can help identify the optimal timeout duration for your setup, balancing efficiency with reliability in file retrieval operations.