HALO Workshop – Implementation Task Sheet

Objective

Implement a battery charging supervision application on the provided AMP QEMU platform using both a classical approach and a HALO-based approach.

What is already provided

• QEMU platform setup
• boot and cores/harts startup
• Zephyr, FreeRTOS, Bare-Metal, and Linux application skeletons
• IPC runtime / shared memory infrastructure
• UART console for Linux
• Virtual sensors / peripherals with query APIs
• All charging logic and state management
• build and run scripts

What you must implement

Hart1 / Zephyr — SensorFusion

• read the sensor values
• aggregate them into SensorFrameIf
• periodically publish SensorFrameIf at 100ms intervals

Hart2 / FreeRTOS — ChargeController

• consume SensorFrameIf
• use provided functions for charging decisions
• publish ChargeCommandIf and ChargeStatusIf at 200ms intervals
• consume OperatorCommandIf if an operator command is received

Hart3 / Bare-metal — SafetyMonitor

• consume ChargeCommandIf
• use provided functions to check final safety behavior
• publish SafetyStateIf at 200ms intervals

Hart4 / Linux — Supervisor

• receive UART console commands
• use provided functions to parse user commands
• convert them into OperatorCommandIf and publish it to ChargeController at 500ms intervals
• consume ChargeStatusIf and SafetyStateIf
• use provided functions to print state and logs to console

Interfaces you must use

Minimum interface contents

SensorFrameIf

• battery voltage in millivolts
• charge current in milliamperes
• battery temperature in degrees Celsius
• breaker state
• fault/status flags

    unsigned int battery_voltage_mv = 0;
    int charge_current_ma = 0;
    float battery_temp_c = 0.0;
    bool breaker_closed = false;
    unsigned int fault_flags = 0;
    

fault_flags definition (bitmask, uint32):

• bit 0 (0x01): over-temperature
• bit 1 (0x02): over-current
• bit 2 (0x04): over-voltage
• bit 3 (0x08): undervoltage
• bit 4 (0x10): breaker open/tripped
• bit 5 (0x20): sensor invalid/stale
• bits 6-31: reserved (must be 0 for now)

Multiple faults can be set at once using bitwise OR. Example: fault_flags = 0x03 means over-temperature and over-current.

ChargeCommandIf

• enable charging
• current limit
• voltage limit
• charging mode

Allowed values for charging_mode: "normal", "fast".

    bool enable_charging = False
    unsigned int current_limit_ma = 0
    unsigned int voltage_limit_mv = 0
    string charging_mode = "normal"
    

ChargeStatusIf

• charger state
• requested current in milliamperes
• requested voltage in millivolts
• fault state

Allowed values for charger_state: "idle", "charging", "complete", "fault".

    string charger_state = "idle"        
    unsigned int requested_current_ma = 0
    unsigned int requested_voltage_mv = 0
    unsigned int fault_state = 0         
    

SafetyStateIf

• safe mode
• breaker open
• charging allowed
• heartbeat

    bool safe_mode = False            
    bool breaker_open = False         
    bool charging_allowed = False     
    unsigned int heartbeat_counter = 0
    

OperatorCommandIf

• command id
• parameter

    unsigned int command_id = 0
    int command_param = 0      
    

Allowed values for command_id:

• 0: no-op (ignore command, keep current state). command_param ignored.
• 1: start charging. command_param ignored.
• 2: stop charging. command_param ignored.
• 3: reset controller/safety state. command_param ignored.
• 4: set mode normal. command_param ignored.
• 5: set mode fast. command_param ignored.
• 6: set current limit in mA. command_param contains the requested current value.
• 7: set voltage limit in mV. command_param contains the requested voltage value.

For unknown command_id values, ignore the command and set an appropriate fault or log entry.

Example commands

• start
• stop
• reset
• mode normal
• mode fast
• set_current 10
• set_voltage 12000

Required scenarios

Nominal scenario

1. Zephyr reads virtual sensor values
2. Zephyr publishes SensorFrameIf
3. FreeRTOS computes charging decision
4. FreeRTOS publishes ChargeCommandIf and ChargeStatusIf
5. Bare-metal updates SafetyStateIf
6. Linux displays current controller and safety state
7. User sends a UART command
8. Linux parses it and forwards OperatorCommandIf
9. FreeRTOS applies the command and updates status

Workshop Group Allocation

1. Five groups as G1 through G5.
2. Group will either start with the classical implementation or the HALO-based implementation first depending on the slip drawn, then switch to the other approach after a fixed time:
   • Two slips: Classical -> HALO
   • Three slips: HALO -> Classical
3. Slips will be shuffled thoroughly in view of participants.
4. One representative from each group will draw exactly one slip.
5. Allocation will be immediately recorded in a log table with the following fields:
   • Group ID
   • Assigned order
   • Time

Implementation Guidelines

Using TODO Tree Extension (Classical & HALO Workshops)

To effectively track and manage your implementation tasks, you must use the TODO Tree extension in VS Code. This extension helps you organize and monitor your work across the codebase.

• Install TODO Tree: Open VS Code Extensions (Ctrl+Shift+X), search for "TODO Tree", and install it.
• Pre-populated TODOs: The skeleton code already contains TODO markers for all required implementation tasks:
  • Classical approach: TODOs prefixed with TODO Classical: X (where X is the task number)
  • HALO approach: TODOs prefixed with TODO HALO: X
• Tracking Progress: The TODO Tree view (accessible via the Activity Bar) displays all TODO items in your workspace, making it easy to see what remains to be completed.
• Completing Tasks: As you implement each TODO item:
  1. Work on the implementation specified by the TODO comment
  2. Once finished, delete the entire TODO marker line from your code
  3. This removes the completed task from the TODO Tree and keeps your list clean
• Regular Review: Check the TODO Tree frequently to track your progress. When the TODO Tree is empty, all required implementation tasks are complete.

Interacting with BMS Simulation via PTY Terminal

Once your implementation is built and running, you can interact with the BMS (Battery Management System) simulation through the console PTY. Use the PTY terminal in VS Code when selecting the task QEMU Sys Run.

• Start Simulation: Run the VS Code task named Qemu Sys Run.
• PTY Terminal: When the QEMU Sys Run executes if you selected PTY, it launches a pseudo-terminal window where you can interact with the running simulation in real-time.
• Send Commands: Use the terminal input to send operator commands to the Supervisor (Hart4 / Linux). Supported commands include:
  • start — Start charging
  • stop — Stop charging
  • reset — Reset controller and safety state
  • mode normal — Set charging mode to normal
  • mode fast — Set charging mode to fast
  • set_current <mA> — Set current limit (e.g., set_current 5000)
  • set_voltage <mV> — Set voltage limit (e.g., set_voltage 12000)
• Monitor Output: The console displays real-time feedback from the applications when you used logging mechanism [APPx], for example:
  • Sensor readings from Hart1 (Zephyr)
  • Charging controller state from Hart2 (FreeRTOS)
  • Safety state updates from Hart3 (Bare-metal)
  • Command acknowledgments and system status from Hart4 (Linux)
• Debugging: Use the PTY terminal output to verify correct data flow between components and to test your command handling implementation end-to-end.

Acceptance checklist

• BMS Sensors are read and SensorFrame is published successfully
• SensorFrameIf is published periodically
• ChargeController computes a charging decision
• SafetyMonitor publishes final safety state
• Supervisor receives UART commands correctly
• Supervisor forwards OperatorCommandIf
• At least one command works end-to-end
• Status is visible on the console

Classical Approach

In the classical approach, you are responsible for implementing all Inter-Process Communication (IPC), synchronization mechanisms, and middleware infrastructure yourself. This approach provides complete control and flexibility but requires careful management of low-level communication details.

Your Responsibilities

• IPC Implementation: Design and implement communication mechanisms between the four harts:
  • Shared memory access and coordination
  • Synchronization primitives if needed (mutexes, semaphores, spin-locks, etc.)
  • Data consistency and coherence strategies if needed
• Interface Management: Manually handle all interface reads/writes:
  • Read from and write to the physical memory addresses specified in the task sheet
  • Ensure proper memory barriers and synchronization points if needed
  • Implement data serialization/deserialization as needed
• Error Handling: Implement error detection:
  • Handle missing or stale data from other components
  • Detect communication failures

Example Structure

A typical classical implementation workflow:

1. Define data structures for each interface (matching the specifications in this task sheet)
2. Implement a simple shared memory protocol (e.g., producer writes, consumer reads with a flag or counter)
3. Add synchronization (e.g., spinlocks or semaphores for critical sections)
4. Implement the application logic for each hart using TODO markers
5. Test individual components first, then verify end-to-end communication
6. Delete TODO markers as you complete each task

HALO system description (HADL)

HALO participants must create/update their HADL system description files in /workspaces/PhdHaloRSG/halo_dist/hadls. After adding or updating HADL files, compose and generate the HALO framework packages using the VS Code tasks named Halo: Compose and Halo: Generate (available in the workspace Tasks menu).

Tip: HALO-specific code snippets are available in VS Code. Just type hml in a HML file or IDL in IDL file etc. Snippets are defined in .vscode/hadl.code-snippets in this workspace.

See an example HADL workflow in the Getting Started guide: Getting Started — example.

Appendix: Diagrams

System overview

Communication flow