Agent Log Helper

Agent Log Logging System - Keil Project Integration Guide

This skill guides you through integrating the agent_log logging system into Keil/MDK projects, based on SEGGER RTT for structured bidirectional communication.

---

Step 1: Copy Source Files

Copy the following files to the target project's LogSystem/ directory:

The agentlog.c and agentlog.h files from this skill's folder.

---

Step 2: Add to Keil Project

Use the keil-modifier skill to create a LogSystem Group and add source files:

# Create LogSystem Group
keil-modifier: create-group "LogSystem"

# Add agent_log.c to LogSystem Group
keil-modifier: add-file "LogSystem" "LogSystem/agent_log.c"

Note: agent_log.h does not need to be manually added to the project; simply #include "agent_log.h" in your code.

---

Step 3: Add Include Path

Add the LogSystem directory to the Keil project include paths:

Options for Target → C/C++ → Include Paths → Add ../LogSystem

---

Step 4: Implement Tick Function

agent_log_get_tick() is a weak symbol that must be implemented by the application layer.

FreeRTOS Implementation Template:

// Implement in your main.c or system.c
#include "agent_log.h"

uint32_t agent_log_get_tick(void)
{
    return xTaskGetTickCount();  // FreeRTOS
}

Bare-metal Implementation Template:

#include "agent_log.h"

extern volatile uint32_t g_sys_tick;  // Your system tick variable

uint32_t agent_log_get_tick(void)
{
    return g_sys_tick;
}

---

Step 5: Initialize the Logging System

Call agent_log_init() during system initialization:

#include "agent_log.h"

int main(void)
{
    // System hardware initialization...

    // Initialize logging system
    agent_log_init();

    // Start task scheduler (if using RTOS)
    vTaskStartScheduler();

    while (1) {
        // Main loop
    }
}

---

API Reference

System Control APIs

| Function | Description | |----------|-------------| | agent_log_init() | Initialize logging system, calls SEGGERRTTInit() | | agent_log_set_level(level) | Set global log level | | agent_log_get_level() | Get current global log level | | agent_log_set_color_enable(enable) | Set color enable flag (1=enable, 0=disable) | | agent_log_get_color_enable() | Get color enable status | | agent_log_get_tick() | Get system tick value (weak symbol, must be implemented by application) |

RTT Data Read APIs

| Function | Description | |----------|-------------| | agent_log_has_data() | Check if RTT downstream buffer has data to read | | agent_log_read(buf, size) | Read data from RTT downstream buffer |

RTOS Task APIs (Optional)

| Function | Description | |----------|-------------| | agent_log_task() | Default RTT command receive task (weak symbol) | | agent_log_task_create() | Create Agent Log task (weak symbol) | | agent_log_parse_cmd(cmd) | Command parsing interface (weak symbol, can be redefined by application) |

Log Macros (Non-formatted Version)

Suitable for cases where only event occurrence needs to be recorded without additional data:

agent_log_dbg(mod, event);    // Debug level
agent_log_inf(mod, event);    // Info level
agent_log_wrn(mod, event);    // Warning level
agent_log_err(mod, event);    // Error level
agent_log_fat(mod, event);    // Fatal error level

Log Macros (Formatted Version)

Suitable for formatted data output:

agent_log_dbg_fmt(mod, event, ...);    // Debug level
agent_log_inf_fmt(mod, event, ...);    // Info level
agent_log_wrn_fmt(mod, event, ...);    // Warning level
agent_log_err_fmt(mod, event, ...);    // Error level
agent_log_fat_fmt(mod, event, ...);    // Fatal error level

Log Macros (With Source Location Version)

Output format: [file:line] [tick][level][module][event] message\r\n

Location information is automatically extracted from __FILE__, __LINE__, __FUNCTION__ for quick log source localization.

No-argument version:

agent_log_dbg_loc(mod, event);    // Debug level
agent_log_inf_loc(mod, event);    // Info level
agent_log_wrn_loc(mod, event);    // Warning level
agent_log_err_loc(mod, event);    // Error level
agent_log_fat_loc(mod, event);    // Fatal error level

With-argument version:

agent_log_dbg_loc_fmt(mod, event, ...);    // Debug level
agent_log_inf_loc_fmt(mod, event, ...);    // Info level
agent_log_wrn_loc_fmt(mod, event, ...);    // Warning level
agent_log_err_loc_fmt(mod, event, ...);    // Error level
agent_log_fat_loc_fmt(mod, event, ...);    // Fatal error level

---

Module List

| Module | Enum Value | Description | |--------|------------|-------------| | SYS | AGENT_LOG_MODULE_SYS | System | | I2C | AGENT_LOG_MODULE_I2C | I2C Communication | | SENSOR | AGENT_LOG_MODULE_SENSOR | Sensor | | UART | AGENT_LOG_MODULE_UART | UART | | ADC | AGENT_LOG_MODULE_ADC | ADC | | GPIO | AGENT_LOG_MODULE_GPIO | GPIO | | TIMER | AGENT_LOG_MODULE_TIMER | Timer |

---

Log Levels

| Level | Enum Value | Description | Typical Usage | |-------|------------|-------------|---------------| | OFF | AGENT_LOG_LEVEL_OFF | Off | Disable all logs | | FAT | AGENT_LOG_LEVEL_FAT | Fatal error | System about to halt or reset | | ERR | AGENT_LOG_LEVEL_ERR | Function failure | Running in degraded mode | | WRN | AGENT_LOG_LEVEL_WRN | Abnormal condition | Can continue | | INF | AGENT_LOG_LEVEL_INF | Normal operation point | Main log flow | | DBG | AGENT_LOG_LEVEL_DBG | Debug info | Disabled during normal operation |

Level Values: OFF(0) 0) { cmdbuf[len] = '\0'; // Custom command handling... } } vTaskDelay(pdMSTO_TICKS(10)); } }

### RTT Command Interaction Example

Send commands via J-Link RTT Viewer or other RTT client:

| Command | Function |
|---------|----------|
| `dbg` | Set log level to DBG (all output) |
| `inf` | Set log level to INF (info and above) |
| `wrn` | Set log level to WRN (warning and above) |
| `err` | Set log level to ERR (error and above) |
| `fat` | Set log level to FAT (fatal only) |
| `off` | Disable all log output |

---

## Log Format

**Standard Format**: `[tick][level][module][event] additional_data\r\n`

**With Source Location Format**: `[file:line] [tick][level][module][event] additional_data\r\n`

Example:

[1234][INF][SYS ][BOOT ] ====== System Init ====== [1235][INF][GPIO ][LEDINIT] LED1 initialized [1240][ERR][I2C ][TIMEOUT ] addr=0x48 retry=3/3 [1241][FAT][SYS ][HALT ] reason=I2CFAIL

[main.c:156] [1234][ERR][I2C ][TIMEOUT ] addr=0x48 retry=3/3 [i2c.c:89] [1256][ERR][I2C ][BUS_ERROR] addr=0x68 flags=0x02

---

## RTT Configuration

- **Channel Number**: `0` (defined by `AGENT_LOG_RTT_CHANNEL`)
- **Buffer Size**: Upstream (log output) recommended 1024 bytes, downstream (command input) recommended 16 bytes or more
- To modify, change `AGENT_LOG_RTT_CHANNEL` macro in `agent_log.h`
- **Note**: Downstream buffer must be large enough to store command strings (recommended 64~128 bytes). If upstream log output is incomplete, first adjust buffer to 2048 bytes or larger

---

## Notes

1. `agent_log_get_tick()` is a **weak symbol** and must be implemented by the application layer
2. Formatted macros use an internal **128-byte temporary buffer**; strings exceeding this will be truncated
3. Logs output all levels by default (DBG); for production release, change to `INF` or `ERR`
4. RTOS task APIs (`agent_log_task`, `agent_log_task_create`, `agent_log_parse_cmd`) are all **weak symbols**; application layer can redefine as needed
5. Default stack size for `agent_log_task()` is **1024 words**, priority is **tskIDLE_PRIORITY + 4**; adjust according to actual requirements

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [changde-tang](https://github.com/changde-tang)
- **Source:** [changde-tang/embedded-skills](https://github.com/changde-tang/embedded-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.