Host-Side Tools
Relevant source files
The following files were used as context for generating this wiki page:The primary host-side tool for interacting with the DutyCycle device is a command-line interface (CLI) accessible over a serial connection. This shell allows for system configuration, control, and debugging by sending text-based commands. The serial connection should be configured to a baud rate of 115200 with an 8N1 (8 data bits, no parity, 1 stop bit) setup.
The CLI is built upon a generic Shell module and is integrated into the firmware's data processing architecture. Commands sent via the serial terminal are parsed and routed to specific handlers that interact with different parts of the system, such as the clock, power management, and motor control. This provides a powerful and flexible way to manage the device's state and behavior from a connected host computer.
Sources: README.md:16-17, Firmware/App/Service/DataProc/DP_Shell.cpp:202-218
Shell Architecture
The CLI is implemented using a reusable Shell module. This module provides the core functionality for handling character input, parsing commands and arguments, and dispatching them to registered functions.
Sources: Firmware/App/Utils/Shell/Shell.h, Firmware/App/Utils/Shell/Shell.c
Initialization and Core Components
The shell is initialized by the DP_Shell data processor. During initialization, it is provided with function pointers for reading and writing characters, which are mapped to the device's SerialIO driver. It is also given a function to get the system tick for timing purposes.
The key components of the shell are:
- Reader/Writer Callbacks: Functions to get a character from and write a character to the serial stream.
- Command List: An array that stores registered commands, mapping command strings to their corresponding handler functions.
- Input Buffer: A buffer to store incoming characters until a complete command line is received (terminated by a carriage return).
- Task Loop: The
shell_task()function, which must be called periodically to process incoming characters and execute commands.
Sources: Firmware/App/Service/DataProc/DP_Shell.cpp:202-218, Firmware/App/Utils/Shell/Shell.h:182-192
The following diagram illustrates the initialization process of the shell within the DP_Shell module.
Command Processing Flow
The shell_task() function is the heart of the CLI. It reads characters from the serial port, handles special characters like backspace, and buffers the input. When a carriage return is detected, it parses the buffered string into a command and its arguments (argc, argv) and searches the command list for a match. If a match is found, the corresponding handler function is executed.
This diagram shows the flow of processing a command from user input to execution.
Command Reference
The DP_Shell module registers a set of commands to interact with the device's systems. Commands are processed using an argparse helper for option parsing.
Sources: Firmware/App/Service/DataProc/DP_Shell.cpp:219-227
| Command | Description | Source File - |
|---|---|---|
help | Lists all available commands. | Firmware/App/Service/DataProc/DP_Shell.cpp:266-270 - |
loglevel | Sets the logging verbosity level (0-4). | Firmware/App/Service/DataProc/DP_Shell.cpp:272-279 |
ps | Dumps memory usage information (stack and heap). | Firmware/App/Service/DataProc/DP_Shell.cpp:281-286 |
publish | Publishes a message to a data processing topic. | Firmware/App/Service/DataProc/DP_Shell.cpp:288-299 |
clock | Manages the Real-Time Clock (RTC). | Firmware/App/Service/DataProc/DP_Shell.cpp:301-370 |
power | Controls device power states like shutdown and reboot. | Firmware/App/Service/DataProc/DP_Shell.cpp:372-408 |
ctrl | Manages motor control and display modes. | Firmware/App/Service/DataProc/DP_Shell.cpp:410-482 |
alarm | Configures alarms and tones. | Firmware/App/Service/DataProc/DP_Shell.cpp:484-573 |
kvdb | Manages the key-value database on the device. | Firmware/App/Service/DataProc/DP_Shell.cpp:575-613 |
Data Interaction with ShellNodeHelper
Most commands interact with the firmware's internal systems via the DataProc framework. The DP_Shell.cpp file uses a ShellNodeHelper template class to simplify this interaction. This helper class subscribes to a specific DataNode (e.g., "Clock", "Power"), and provides pull and notify methods to get data from or send commands to that node.
The following sequence diagram shows how the power command uses ShellNodeHelper to send a SHUTDOWN command to the Power data node.
power Command
This command controls the device's power state.
| Argument | Description | Example Usage |
|---|---|---|
-c | The power command to execute. | power -c SHUTDOWN |
cmd | Valid commands: SHUTDOWN, REBOOT. | power -c REBOOT |
The available commands are defined in the POWER_CMD enum.
Sources: Firmware/App/Service/DataProc/DP_Shell.cpp:394-397, Firmware/App/Service/DataProc/Def/Power.h:21-28
clock Command
This command is used to get and set the device's real-time clock.
| Argument | Description | Example Usage |
|---|---|---|
-c | The clock command to execute. Must be SET. | clock -c SET -y 2024 -m 6 -d 8 -H 10 |
-y | Year | -y 2024 |
-m | Month | -m 12 |
-d | Day | -d 25 |
-H | Hour | -H 23 |
-M | Minute | -M 59 |
-S | Second | -S 30 |
When executed without arguments, it prints the current time. When used with the -c SET command and time parameters, it updates the system time.
Sources: Firmware/App/Service/DataProc/DP_Shell.cpp:329-344
ctrl Command
This command provides control over the motor and other core device functions.
| Argument | Description - |
|---|---|
-c cmd | The control command to execute. Valid commands: SWEEP_TEST, ENABLE_CLOCK_MAP, LIST_CLOCK_MAP, SET_MOTOR_VALUE, SET_CLOCK_MAP, SET_MODE, SHOW_BATTERY_USAGE. |
-H hour | The hour to set for clock map calibration. - |
-M motor | The raw motor value to set. - |
--mode | Display mode: 0 for COS_PHI (power factor meter style), 1 for LINEAR. - |
Sources: Firmware/App/Service/DataProc/DP_Shell.cpp:419-482
Conclusion
The serial CLI is an essential tool for developers and advanced users to configure, control, and debug the DutyCycle device. It exposes a wide range of internal functionalities through a structured command system, leveraging a reusable shell module and the firmware's data processing architecture. By understanding the available commands and their arguments, users can finely tune the device's behavior, from setting the time to calibrating the motor and managing power states.
Sources: README.md:16-17, Firmware/App/Service/DataProc/DP_Shell.cpp