Getting Started
Relevant source files
The following files were used as context for generating this wiki page:- README.md
- Firmware/App/Version.h
- Firmware/App/Config/Config.h
- Firmware/App/Utils/Shell/Shell.h
- Firmware/App/Utils/Shell/Shell.c
- Firmware/App/Service/HAL/HAL_Config.h
- Firmware/App/Service/DataProc/DP_Version.cpp
- Firmware/Vendor/Artery/Platform/AT32F421/MDK-ARM/RTE/_AT32F421/RTE_Components.h
- Firmware/Vendor/Artery/ArduinoAPI/Arduino.h
This document provides a comprehensive guide for setting up, compiling, and configuring the DutyCycle project. The DutyCycle is a "Work-Life Duty Cycle Clock" designed to represent the passage of time using an analog meter, offering a unique, "hardcore poetic" perspective on life's energy consumption. The firmware is built for the AT32F421 microcontroller.
This guide covers obtaining the source code, compiling the firmware with Keil, configuring the system via a serial command-line interface, and understanding the basic hardware operations and time-reading conventions.
Project Overview
The project provides firmware for a custom clock device. Key information about the firmware is defined in the source files.
| Item | Value | Source |
|---|---|---|
| Firmware Name | DutyCycle | Firmware/App/Version.h:26 |
| Software Version | v1.2 | Firmware/App/Version.h:27 |
| Hardware Version | v1.3 | Firmware/App/Version.h:28 |
| Author | _VIFEXTech | Firmware/App/Version.h:29 |
| Website | https://... | Firmware/App/Version.h:30 |
| Build Date & Time | Compiler timestamp | Firmware/App/Service/DataProc/DP_Version.cpp:100-101 |
| Compiler | ARMCC, GCC, or MSVC | Firmware/App/Service/DataProc/DP_Version.cpp:40-53 |
| License | GNU GPLv3 | Firmware/App/Utils/Shell/license.txt |
Setup and Compilation
To get started with the DutyCycle firmware, you need to clone the repository and compile it using the specified tools.
Prerequisites
- Keil MDK-ARM: Version 5.25 or higher is required for compilation.
Sources: README.md:19-20
1. Get the Source Code
Clone the repository and its submodules using the following command:
git clone https://github.com/FASTSHIFT/DutyCycle.git --recursive
Sources: README.md:14-16
2. Compile the Firmware
The compilation process uses Keil MDK. The following diagram illustrates the workflow.
This diagram shows the steps from cloning the source code to compiling the final firmware.
Sources: README.md:18-20
The project is configured for an ArteryTek AT32F421 device and includes standard peripheral libraries such as ADC, CRM, DMA, GPIO, I2C, TMR, and USART.
Sources: Firmware/Vendor/Artery/Platform/AT32F421/MDK-ARM/RTE/_AT32F421/RTE_Components.h:13-38
System Configuration
The device is configured using a command-line shell over a serial connection.
Serial Connection
Connect to the device using any serial terminal application with the following settings:
| Parameter | Value |
|---|---|
| Baud Rate | 115200 |
| Data Bits | 8 |
| Parity | None |
| Stop Bits | 1 |
Sources: README.md:22-23, Firmware/Vendor/Artery/Platform/AT32F421/Config/mcu_config.h:22
Command Shell
The firmware includes a command shell for interactive configuration. The shell is initialized with reader and writer functions to handle character I/O over the serial port.
The core components of the shell are:
shell_init(): Initializes the shell, registers I/O callbacks, and prints a startup message.shell_register(): Adds a new command and its handler function to the shell's command list.shell_task(): The main processing loop that reads characters, parses commands, and executes them. It should be called frequently.
Sources: Firmware/App/Utils/Shell/Shell.h, Firmware/App/Utils/Shell/Shell.c
The following sequence diagram shows how the shell processes a command.
This diagram illustrates the flow of a command from user input to execution and response within the firmware's shell.
Sources: Firmware/App/Utils/Shell/Shell.c:266-330
Hardware Pin Configuration
The firmware supports two hardware versions (v1.1 and v1.2), with different pin mappings defined in HAL_Config.h. The HAL_PinRemap macro selects the correct pin based on the hardware version.
| Feature | Pin (HW v1.2) | Pin (HW v1.1) |
|---|---|---|
| Motor Output 1 | PA2 | PA2 |
| Motor Output 2 | PA3 | PA3 |
| Buzzer | PB1 | PB2 |
| Battery Detect | PB0 | PB1 |
| Power Enable | PA6 | PA7 |
| Button Select | PA7 | PB0 |
Sources: Firmware/App/Service/HAL/HAL_Config.h:25-43
Usage
Button Operations
The device is controlled with a single button.
| Action | Result |
|---|---|
| Single Click (off) | Powers on the device. An audible tone confirms power-on. The default time is set to the firmware's compilation time. |
| Long Press (on) | Press and hold for >10 seconds to power off. An audible tone confirms power-off, and the meter pointer returns to zero. |
| Single Click (on) | Displays the remaining battery level. The meter points to 0.5 (top) for 100% and 0.5 (bottom) for 0%. |
| Double Click (on) | Toggles mute mode. When muted, all sounds (button tones, alarms, hourly chimes) are silenced. Double-click again to unmute. |
Sources: README.md:28-36
Reading the Time
The analog meter's reading is mapped to the time of day. The interpretation depends on the meter's faceplate style.
Power Factor Meter Mode
This mode uses a non-linear scale.
| Meter Reading | Time |
|---|---|
| 0.5 (top) | 05:00 |
| 0.7 (top) | 07:00 |
| 0.9 (top) | 09:00 |
| 1.0 | 12:00 |
| 0.9 (bottom) | 21:00 |
| 0.7 (bottom) | 01:00 |
| 0.5 (bottom) | 04:59 |
Sources: README.md:42-52
Voltage/Current (Linear) Meter Mode
This mode uses a linear scale from 0 to 24.
| Meter Reading | Time |
|---|---|
| 0 | 00:00 |
| 5 | 05:00 |
| 10 | 10:00 |
| 15 | 15:00 |
| 20 | 20:00 |
| 24 | 23:59 |
Sources: README.md:55-64