Command Line Interface
======================

The firmware provides a command line interface (CLI) over a serial connection, enabling remote interaction with the microcontroller. This interface can be accessed through two primary communication channels:

- **USB CDC** (Communication Device Class) Serial Port: The firmware exposes a virtual serial port over USB, using the USB CDC protocol. This allows the microcontroller to be accessed as a standard serial device on a Linux or Windows host, facilitating communication over a virtual COM port.

- **HotRIO Sideband Communication** (FPGA Interface): Alternatively, the FPGA in the HotRIO ecosystem can facilitate access to the CLI through the sideband communication channel. This provides an additional means of interacting with the firmware, independent of the USB interface, but still allowing full access to the system's command interface.

The CLI itself offers a Linux-like command shell, enabling users to perform various system-level tasks remotely. Key features of the CLI include:

- **Device Configuration and Management**: The CLI allows users to configure microcontroller settings, manage peripheral devices, and change operational statuses, using familiar Linux-style commands. These tasks include adjusting parameters, toggling operational modes, or managing device behavior.

- **Filesystem Interaction**: Users can navigate, manipulate, and transfer files within the microcontroller's filesystem. The system supports the Kermit file transfer protocol, enabling secure file transfers between the host and the microcontroller's FATFS filesystem or virtual filesystem.

- **Real-Time Status Monitoring and Diagnostics**: Through the CLI, users can query system status, obtain logs, and perform diagnostic checks, allowing for real-time monitoring of the microcontroller's performance and health.

The command parser in the firmware is designed to operate in a single-threaded environment, which means it can handle commands from only one communication channel at a time. When the CLI is accessed via the USB CDC serial port, it exclusively listens to the USB interface, and when accessed via the FPGA sideband communication, it exclusively listens to the sideband channel. Both interfaces cannot be used concurrently, and the firmware will process commands from whichever interface is actively being used, at that moment.

This single-threaded design simplifies command handling but also imposes the limitation that the system can only interact with one communication source at a time, either USB or sideband. The user must select the desired communication method to interact with the firmware, as the two channels cannot operate in parallel.


Supported commands
------------------

Following, the user will find a collection of supported commands that can be used on the HotRIO CLI:

.. toctree::
   :maxdepth: 1
   
   cat
   cd
   echo
   fpga
   iface
   ls
   lscpu
   mkfs
   reboot
   run