# Agent Log Helper

> A guidance skill for integrating the agent_log logging system into Keil/MDK projects. Triggers: (1) User says "add agent_log", "add logging system", (2) User needs structured logging in Keil project, (3) User wants to add log output but doesn't know where to start, (4) User needs log initialization template or tick function implementation. Even if user just says "add log" or "use RTT logging", th…

- **Type:** Skill
- **Install:** `agentstack add skill-changde-tang-embedded-skills-agent-log-helper`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [changde-tang](https://agentstack.voostack.com/s/changde-tang)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [changde-tang](https://github.com/changde-tang)
- **Source:** https://github.com/changde-tang/embedded-skills/tree/main/agent-log-helper

## Install

```sh
agentstack add skill-changde-tang-embedded-skills-agent-log-helper
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 agent_log.c and agent_log.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:

```bash
# 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**:

```c
// 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**:

```c
#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:

```c
#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 SEGGER_RTT_Init() |
| `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:

```c
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:

```c
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**:
```c
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**:
```c
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) {
                cmd_buf[len] = '\0';
                // Custom command handling...
            }
        }
        vTaskDelay(pdMS_TO_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  ][LED_INIT] LED1 initialized
[1240][ERR][I2C   ][TIMEOUT ] addr=0x48 retry=3/3
[1241][FAT][SYS   ][HALT    ] reason=I2C_FAIL

[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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-changde-tang-embedded-skills-agent-log-helper
- Seller: https://agentstack.voostack.com/s/changde-tang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.