aircable/esp-logcat

readme

# ESP Logcat (Log Sink + TCP Logcat)

Android-style logcat for ESP-IDF: captures `ESP_LOGx` output, writes it to a rolling log file,
and streams the same output over a TCP connection. This is designed for **remote debugging**,
especially when a serial console is not practical.

## Intent & Motivation

- Provide **remote, real-time debug logs** over TCP.
- Persist logs on the device for later inspection.
- Make troubleshooting possible in deployed systems without physical access.

## What This Component Provides

- **Log sink** that hooks `esp_log_set_vprintf()`.
- **Rolling file storage** (`logcat.txt` + `logcat.prev`).
- **TCP logcat server** that:
  - replays stored logs on connect, then
  - streams live logs afterward.
- A **generic TCP server** implementation that can be reused for other features.

When using this component in WishMesh, the built-in TCP server replaces any local `tcp_server.c`
implementation (i.e., you do **not** need a separate TCP server component in your app).

## Testing the component
Use github project https://github.com/aircable/logcat-test.git as a minimal test.

## Usage

1) Ensure your filesystem is mounted (e.g., LittleFS at `/`).
2) Initialize logcat early in your app:

```c
#include "log_sink.h"

esp_err_t err = log_sink_init();
if (err != ESP_OK) {
    // Fail-fast: prerequisites missing (filesystem not mounted, etc.)
}
```

To disable TCP streaming at runtime:
```c
log_sink_set_tcp_enabled(false);
```

## Fail-fast prerequisites

- The log directory must be mounted before calling `log_sink_init()`.
- Default base path is `/` (configurable via Kconfig).
- If the directory is missing or the file cannot be opened, `log_sink_init()` returns an error
  and **does not** install the log hook.

#### Logcat Access (Host Commands)

Linux / macOS (netcat):
```
nc <device-hostname-or-ip> 11884
```

Windows:
- PowerShell (built-in TCP client):
```
Test-NetConnection <device-hostname-or-ip> -Port 11884
```
  (Use this to verify connectivity; it does not stream logs.)
- If you have `ncat` (Nmap) or `nc` installed:
```
ncat <device-hostname-or-ip> 11884
```
or
```
nc <device-hostname-or-ip> 11884
```

### Kconfig

- `CONFIG_ESP_LOGCAT_TCP_PORT` (default `11884`)
- `CONFIG_ESP_LOGCAT_DIR` (default `/image`)