HotRIOCLI

Introduction

This section is provides documention for the HotRIOCLI deployment tool, a Python CLI-based tool designed to manage the filesystem, FPGA boot status, and flashing procedures of both the microcontroller and the FPGA onboard the module. HotRIOCLI provides a convenient interface for controlling and configuring the hardware components of your system, facilitating efficient development and debugging processes.

Features

HotRIO offers the following key features:

Filesystem Management: Easily navigate and manipulate files on the connected microcontroller’s filesystem (allocated on the external EEPROM).
FPGA Boot Status Control: View and configure the boot status of the FPGA module, allowing for control of the FPGA status (boot, halt and reboot operations).
Flashing Procedures: Streamlined flashing procedures for updating firmware on both the microcontroller and FPGA directly from the USB port, without the need to use a debug probe.

Installation

The HotRIOCLI tool source code can be found under the Tools folder in the HotRIO-Software repository. While no installation process is required to execute the application, resolving several Python module dependencies is necessary. The following list outlines the required dependencies:

pyserial
pyusb
typing
dataclasses

To ensure smooth execution of the application, it is advisable to use the pip package manager to install these dependencies if they are not already available in your system. You can install them by issuing the following command:

pip install <dependency>

USB permissions

Ensuring proper permissions for USB devices on Linux is crucial to guarantee the seamless operation of tools without encountering issues. USB devices, such as the HotRIO microcontroller USB endpoint, often necessitate specific permissions for effective access and manipulation by applications. In the following, we will outline the necessary steps to configure permissions on Linux systems, providing appropriate access to the HotRIO USB device for applications:

Ensure that the user intended to execute the tool is a member of the plugdev Linux group. This group serves as the default mechanism granting access to USB devices connected to the machine.
- If the plugdev group is not available on your Linux machine, create it by executing the command: sudo groupadd plugdev.
- If the user is not currently part of the plugdev group, add them by executing the command: sudo usermod -aG plugdev <user>.
Once the designated user is a member of the plugdev group, proceed to execute the script setup.sh located within the HotRIOCLI folder in this repository. This script is designed to adjust USB permission rules, restricting access solely to HotRIO USB devices and STM32 DFU devices for the plugdev group. It is recommended to run this script only once per machine, as the permissions are stored in a specific file and remain unchanged during repository updates or system reboots. Additionally, executing this script may require sudo permissions to modify USB rules effectively.

Warning

While users might be tempted to execute the tool with superuser permissions, it is strongly discouraged to do so. On certain Linux machines, processes with elevated permissions have been observed inspecting serial ports upon connection, a process that may consume considerable time, typically in the order of tens of seconds. Linux incorporates a mechanism for locking such serial ports to ensure exclusive access by an application, a safeguard overridden by elevated permissions.

The tool’s software accounts for this behavior by patiently waiting for any process, regardless of permission level, to conclude its usage of the serial port before attempting communication with the modules. If the user opts to execute the tool with superuser privileges, the tool would proceed with attempting communication with the device even if another process is currently utilizing the port. This action may lead to a communication error and subsequent application crash.

Users are strongly advised to follow the setup steps outlined in the preceding section to execute the application with user-level permissions, thus mitigating the risk of such tool malfunctions.

Upon successful installation, the HotRIOCLI tool can be initialized from the terminal by executing the source.sh script located within the HotRIOCLI folder. This script configures the application to be callable from any directory within the system using the command HotRIOCLI.

Usage

The utilization of this interface is quite straightforward. The user is presented with a Linux-like shell, which emulates a set of commands and functionalities applicable to the HotRIO module.

The interface initiates a command line displaying an indicator denoting the currently attached device within brackets and a filesystem path, enabling the user to navigate and manage it using appropriate commands. Initially, the interface remains detached from any device, thus displaying [Detached] as the target device in the prompt.

For effective utilization of the interface with a device, the user must first attach the interface to the target device by executing the “connect” command on the command line interface (CLI). Upon successful attachment, the [Detached] indicator will alter to [<Serial number of the module>], indicating that the tool is presently attached to the specified module as the target. This process remains applicable even when the target module is in DFU mode, albeit the indicator will display [DFU device].

Once a target is connected to the interface, the user can navigate the filesystem using the commands detailed in the subsequent section (e.g., ls, mkdir, mkfs…) to manage the filesystem accordingly. Additionally, the user can employ any of the commands outlined in the subsequent section.

Available commands

This section offers a comprehensive overview of the current commands and functionalities accessible within the HotRIOCLI interface. It aims to provide users with detailed explanations, usage instructions, and examples to facilitate efficient utilization of the interface for supported functionalities.

Accessing help documentation Users can conveniently access documentation directly within the CLI interface. By utilizing the command help <command>, users can retrieve specific details for a particular command. For a broader overview encompassing all available commands, users can issue the command help.

List of available commands

cd : Change directory to a given path.

Usage:
    cd <path>

Args:
    path: Path to change to, can be either relative or absolute.

clear : Clear the terminal screen.

connect : Connect the interface to a target HotRIO device.

Usage:
    connect [-h] [-y]

Options:
    -y       Force connection without asking for confirmation.

disconnect : Disconnect from the current target device.

exit : Quit the interface.

flash : Flash a new firmware for one of the onboard targets (mcu or fpga) from a file

Usage:
    flash [--fpga or --mcu] -f <firmware file>

fpga : Control or read the boot status of the FPGA.

Usage:
    fpga [--enable | --disable | --reboot]
    If no parameter is specified, the FPGA boot state is displayed.

Options:
    --enable    Enable the boot sequence of the FPGA.
    --disable   Disable the FPGA by forcing reset state.
    --reboot    Reboot the FPGA.

help : List available commands with “help” or detailed help with “help cmd”.

ls : List contents of a folder.

Usage:
    ls [path]

Args:
    path (optional): Path for the ls query command (absolute or relative).

mkdir : Create a folder in the filesystem.

Usage:
    mkdir <path>

Args:
    path: Path of the new folder to be created, can be either relative or absolute.

mkfs : Format the onboard filesystem.

Usage:
    mkfs [-y] [-h]

Options:
    -y       Force format without asking for confirmation.
    -h       Show help message and exit.

quit : Quit the interface.

reboot : Reboot the attached HotRIO module.

vim : Open a file for editing using the Vim editor.

Usage:
    vim <filePath> [-h]

Args:
    filePath: Path to the file to be edited, either as a relative or absolute path.