DutyCycle Wiki
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- Firmware/App/Version.h
- Firmware/App/Service/DataProc/DP_Shell.cpp
- Firmware/App/Utils/Shell/Shell.h
- Firmware/Vendor/Artery/Application/HAL/HAL_Config.h
- Firmware/App/Service/DataProc/DP_Version.cpp
- Firmware/App/Service/DataProc/Def/Power.h
- Firmware/App/Service/DataProc/Def/Version.h
- Firmware/Vendor/Artery/Platform/AT32F421/Config/mcu_config.h
- Firmware/Vendor/Artery/ArduinoAPI/WireBase.h
Introduction
The DutyCycle project is a "Work-Life Duty Cycle Clock," an embedded system designed to represent time in an unconventional, analog format using a meter display. The firmware is built for the Artery AT32F421 microcontroller. The system provides a unique way to visualize the passage of time, mapping hours onto the scale of an industrial-style meter.
The device is configurable via a serial command-line interface, allowing users to set the time, control the motor, and manage other system settings. It supports physical button interactions for basic operations like power on/off, checking battery level, and muting sounds. The firmware architecture is modular, with a Hardware Abstraction Layer (HAL), data processing services, and utility libraries.
Sources: README.md, Firmware/Vendor/Artery/Platform/AT32F421/MDK-ARM/RTE/_AT32F421/RTE_Components.h
System Architecture
The firmware is structured into several key layers: Application, Services, HAL, and Utilities. The Application layer orchestrates the main device logic. The Services layer, particularly DataProc, manages application data and state. The HAL provides an interface to the microcontroller's peripherals, and the Utilities section contains shared components like the command shell.
This diagram illustrates the high-level software architecture of the DutyCycle firmware.
Firmware Versioning
The firmware maintains version information for the software, hardware, and build environment. This data is exposed through the Version data processing module and can be queried.
| Property | Macro | Description |
|---|---|---|
| Firmware Name | VERSION_FIRMWARE_NAME | The name of the firmware, "DutyCycle". |
| Software | VERSION_SOFTWARE | The software version, e.g., "v1.2". |
| Hardware | VERSION_HARDWARE | The compatible hardware version, e.g., "v1.3". |
| Author | VERSION_AUTHOR_NAME | The author's name, "_VIFEXTech". |
| Website | VERSION_WEBSITE | The project's GitHub repository URL. |
| Compiler | VERSION_COMPILER | The compiler used for the build (e.g., ARMCC). |
| Build Date | __DATE__ | The date of the firmware compilation. |
| Build Time | __TIME__ | The time of the firmware compilation. |
The DP_Version class is responsible for collecting this information and logging it at startup.
Sources: Firmware/App/Version.h, Firmware/App/Service/DataProc/DP_Version.cpp:38-51, Firmware/App/Service/DataProc/Def/Version.h
Hardware Configuration
The firmware is configured to work with specific hardware pins on the AT32F421 MCU. The HAL_Config.h file defines pin mappings for different hardware revisions (v1.1 and v1.2).
Pin Mappings
| Feature | v1.2 Pin | v1.1 Pin | Config Macro |
|---|---|---|---|
| Motor Out 1 | PA2 | PA2 | CONFIG_MOTOR_OUT1_PIN |
| Motor Out 2 | PA3 | PA3 | CONFIG_MOTOR_OUT2_PIN |
| Buzzer | PB1 | PB2 | CONFIG_BUZZ_PIN |
| Battery Detect | PB0 | PB1 | CONFIG_BATT_DET_PIN |
| Power Enable | PA6 | PA7 | CONFIG_PWR_EN_PIN |
| Button Select | PA7 | PB0 | CONFIG_BUTTON_SEL_PIN |
Sources: Firmware/Vendor/Artery/Application/HAL/HAL_Config.h:29-47
MCU Configuration
Core MCU and peripheral settings are defined in mcu_config.h.
| Parameter | Value | Description |
|---|---|---|
SYSTICK_TICK_FREQ | 1000 Hz | System tick frequency. |
SERIAL_RX_BUFFER_SIZE | 64 bytes | Buffer size for serial communication. |
WIRE_BUFF_SIZE | 32 bytes | Buffer size for I2C communication. |
PWM_RESOLUTION_DEFAULT | 1000 | Default resolution for PWM signals. |
PWM_FREQUENCY_DEFAULT | 10000 Hz | Default frequency for PWM signals. |
CONFIG_WATCHDOG_TIMEOUT | 10 seconds | Watchdog timeout period. |
Sources: Firmware/Vendor/Artery/Platform/AT32F421/Config/mcu_config.h, Firmware/App/Config/Config.h:25-27
Serial Shell Interface
The primary method for configuring the DutyCycle device is through a serial shell. It operates at a baud rate of 115200 with an 8N1 configuration. The shell is implemented using a generic shell library and is managed by the DP_Shell data processing module.
Sources: README.md:18-20, Firmware/App/Service/DataProc/DP_Shell.cpp
Initialization and Task Loop
The DP_Shell class initializes the shell, providing callback functions for reading from and writing to the serial device, and for getting the system tick. The shell_task() function is called continuously within the main application loop to process incoming characters and execute commands.
This sequence diagram shows how the shell is initialized and how a command is processed.
Shell Commands
The shell provides several commands to interact with the system's data processing nodes.
| Command | Description | Example Usage |
|---|---|---|
help | Lists all available commands. | help |
loglevel | Sets the logging verbosity level (0-4). | loglevel 3 |
ps | Dumps memory usage information. | ps |
publish | Publishes a message to a data processing topic. | publish MyTopic some_data |
clock | Sets the system time. | clock -c SET -y 2024 -m 6 -d 8 -H 10 |
power | Controls system power state. | power -c SHUTDOWN |
ctrl | Controls the motor and display modes. | ctrl -c SET_MOTOR_VALUE -M 500 |
alarm | Manages alarms and notification sounds. | alarm -c SET -i 1 -H 7 -M 30 |
kvdb | Manages the key-value database. | kvdb -c LIST |
Sources: Firmware/App/Service/DataProc/DP_Shell.cpp:265-555
This flowchart shows the logic for handling a command like power.
Device Operation
Button Controls
The device has a single button for user interaction.
| Action | State | Result |
|---|---|---|
| Single Click | Off | Turns the device on. Default time is the firmware build time. |
| Long Press (>10s) | On | Turns the device off. The meter pointer returns to zero. |
| Short Press | On | Displays the remaining battery level. |
| Quick Double Click | On | Toggles mute state for all sounds (button clicks, alarms, etc.). |
Sources: README.md:23-30
Time Display Modes
The device has two modes for displaying the time, which map the 24-hour day onto the meter's scale.
Power Factor Meter Mode
This mode uses a non-linear scale, common on power factor meters.
| Meter Value | Time |
|---|---|
| 0.5 (upper) | 05:00 |
| 0.7 (upper) | 07:00 |
| 0.9 (upper) | 09:00 |
| 1.0 | 12:00 |
| 0.9 (lower) | 21:00 |
| 0.7 (lower) | 01:00 |
| 0.5 (lower) | 04:59 |
Sources: README.md:36-46
Linear Voltage/Current Meter Mode
This mode uses a simple linear scale from 0 to 24.
| Meter Value | Time |
|---|---|
| 0 | 00:00 |
| 5 | 05:00 |
| 10 | 10:00 |
| 15 | 15:00 |
| 20 | 20:00 |
| 24 | 23:59 |
Sources: README.md:48-57
Conclusion
The DutyCycle project is a creative fusion of industrial aesthetics and modern embedded technology. It provides a functional yet artistic timepiece, with a well-structured firmware architecture based on the AT32F421 MCU. Its configurability through a serial shell interface offers developers and advanced users a powerful way to customize its behavior, from setting the time to modifying the alarm tones and display mappings. The use of a data processing service bus allows for modular and extensible features.
Sources: README.md, Firmware/App/Service/DataProc/DP_Shell.cpp