--- name: ulogger-data-client description: Use the ulogger-data-client CLI to capture device logs, query metrics, push log configurations, create firmware deployments, and download/integrate certificate bundles on the uLogger platform. --- # SKILL: ulogger-data-client ## Executable location The CLI binary is installed at: ``` c:\Users\speed\.agents\skills\ulogger-data-client\ulogger-data-client.exe ``` When running commands, use the full path or add the directory to `$env:PATH`. All examples below use `ulogger-data-client` as a shorthand. This skill covers three primary workflows using the `ulogger-data-client` CLI: 1. **Log capture & troubleshooting** — Collect log evidence when investigating firmware behavior, device incidents, ingestion issues, or customer-reported failures. 2. **Deployment creation** — Create firmware deployments that mirror what the web application does from the Deployment Monitor. 3. **Certificate bundle & project integration** — Download device certificates and integrate uLogger into Python or embedded C/C++ projects. --- # Part 1: Log Capture & Troubleshooting ## Goal Capture the right logs quickly, use safe defaults, and produce actionable troubleshooting output. ## Required inputs - **API token** (`--token` or `ULOGGER_API_TOKEN` env var) — recommended, or - **Certificate** (`--cert`) and **private key** (`--key`) — for mTLS auth - Time window (`--start`, optional `--end`) - Optional application filter (`--application-id`) - Optional device filter (`--device-serial`) - Optional time basis (`--time-field`: `_time` or `inserted_at`) - Optional result limit (`--limit`) - For log config: `--log-level`, `--modules` (or `--module-flags`), `--config-timeout` - For module lookup: `--list-modules`, `--application-id`, `--device-serial` Do not run log queries until authentication credentials are available. ## Standard troubleshooting flow 1. Verify service availability. 2. Query broad logs for the target window. 3. Narrow by app/device if the result set is large. 4. Switch to `inserted_at` when device clock drift is suspected. 5. Return a short incident summary and key log lines. ## Command recipes ### 1) Health check ```bash # With API token (recommended) ulogger-data-client --token --health # With mTLS certificate ulogger-data-client --cert --key --health ``` ### 2) Recent logs (first-pass) ```bash ulogger-data-client --token --start 1h ``` ### 3) Filter by application ```bash ulogger-data-client --token --start 24h --application-id ``` ### 4) Filter by device serial ```bash ulogger-data-client --token --start 24h --device-serial ``` ### 5) Use ingest time for unreliable device clocks ```bash ulogger-data-client --token --start 2h --time-field inserted_at ``` ### 6) Limit output for rapid triage ```bash ulogger-data-client --token --start 1h --limit 100 ``` ### 7) Push a log configuration to a device ```bash # Using module names (preferred — the server resolves names to the bitfield) ulogger-data-client --token \ --send-log-config \ --application-id --device-serial \ --log-level DEBUG --modules SYSTEM,SENSOR --config-timeout 300 # Using raw module_flags (legacy — hexadecimal bitfield) ulogger-data-client --token \ --send-log-config \ --application-id --device-serial \ --log-level DEBUG --module-flags 29 --config-timeout 300 ``` Use `--modules` with comma-separated module names (e.g. `SYSTEM,SENSOR,COMM`) to enable specific modules. Use `--module-flags 4294967295` (`0xFFFFFFFF`) to enable all modules when using the raw bitfield. The device reverts to its default configuration after `--config-timeout` seconds. Valid log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. ### 8) List available log modules for a device ```bash ulogger-data-client --token \ --list-modules \ --application-id --device-serial ``` Returns the module names and their bit positions from the device's AXF file. Use this to discover which modules are available before pushing a log config. ## Interactive log config workflow When the user wants to enable logging for specific modules but doesn't know the module names: 1. **List modules** — Run `--list-modules` with the device's application ID and serial to discover available modules. 2. **Push config** — Run `--send-log-config` with `--modules NAME1,NAME2` using the discovered names. Example: ```bash # Step 1: Discover modules ulogger-data-client --token --list-modules --application-id 965690 --device-serial 1001 # Step 2: Enable specific modules ulogger-data-client --token --send-log-config \ --application-id 965690 --device-serial 1001 \ --log-level INFO --modules SYSTEM,SENSOR --config-timeout 300 ``` If the user says "enable info level logging for the SYSTEM and SENSOR modules on device 12345", run Step 2 directly (the server validates module names and returns an error listing available modules if a name is invalid). ## Time window guidance - Start with `--start 1h` for active incidents. - Use `24h` for intermittent issues. - Prefer explicit RFC3339 windows for postmortems. - Keep windows narrow when no filters are applied. ## Interpretation tips - `_time` represents device-reported event time. - `inserted_at` represents ingest timestamp at the backend. - Large `_time` vs `inserted_at` skew can indicate RTC drift, reconnect buffering, or delayed uploads. ## Expected response shape Key fields commonly used in analysis: - `_msg` - `_time` - `inserted_at` - `application_id` - `device_serial` - `level` - `version` - `git` ## Output format Report: 1. Exact command(s) run. 2. Time basis used (`_time` or `inserted_at`). 3. Filters applied (if any). 4. Count of logs returned. 5. Top findings and suspected root cause. 6. Suggested next capture step if evidence is incomplete. ## Safe defaults - Do not run unbounded queries. - Use `--limit` during initial triage. - Ask before expanding to long windows with no filters. --- # Part 2: Deployment Creation ## Goal Guide the user through creating a firmware deployment by collecting the required parameters (application, device type, version) and calling the CLI to create it. Use safe defaults and confirm before creating. ## Required inputs - **API token** (`--token` or `ULOGGER_API_TOKEN` env var) — recommended, or - **Certificate** (`--cert`) and **private key** (`--key`) — for mTLS auth ## Optional inputs (will be prompted if not provided) - **Application ID** — numeric ID of the target application - **Device type** — the hardware device type to target - **Version** — the firmware version to deploy ## Default values | Parameter | Default | Description | |-----------|---------|-------------| | `--phase` | 1 | Deployment rollout phase (1-10) | | `--timeout-hours` | 6 | Hours before deployment expires | | `--auto-advance` | false | Do not auto-advance to next phase | | `--notes` | (empty) | Optional deployment description | ## Interactive deployment workflow Follow these steps in order. Skip steps where the user has already provided the value. ### Step 1: Verify authentication Ensure the user has provided `--token`, set the `ULOGGER_API_TOKEN` environment variable, or provided `--cert`/`--key`. Do not proceed without credentials. When `ULOGGER_API_TOKEN` is set, the `--token` flag can be omitted from all commands. ### Step 2: Select application If the user has not specified an application ID or name: ```bash ulogger-data-client --token --list-applications ``` Present the returned list to the user and ask them to select one. The output shows both the application name and numeric ID. If the user provides an application **name** rather than an ID, use the list to map the name to its numeric ID. ### Step 3: Select device type If the user has not specified a device type: ```bash ulogger-data-client --token --endpoint device-types --application-id ``` Present the returned device types to the user and ask them to select one. ### Step 4: Select version If the user has not specified a version: ```bash ulogger-data-client --token --endpoint artifact-versions --application-id --device-type --limit 10 ``` Present the 10 most recent versions to the user and ask them to select one. The output includes version string, device type, and upload timestamp. ### Step 5: Confirm and create Summarize the deployment parameters before creating: ``` Application ID: Device type: Version: Phase: 1 Timeout: 6 hours Auto-advance: disabled ``` Ask the user to confirm, then run: ```bash ulogger-data-client --token --create-deployment \ --application-id \ --device-type \ --version \ --phase 1 \ --timeout-hours 6 \ --auto-advance=false ``` ### Step 6: Report result On success, report the `deployment_id` returned by the command. Example: ``` ✓ Deployment created successfully! deployment_id: 42 device_type: tracker_v2 version: 1.2.3 phase: 1 timeout_at: 2026-04-30T18:00:00+00:00 auto_advance: false ``` On error 409 (conflict), explain that an active deployment already exists for that device_type + phase combination. Suggest waiting for the existing deployment to expire or choosing a different phase. ## Deployment command recipes ### List applications ```bash ulogger-data-client --token --list-applications ``` ### List device types for an application ```bash ulogger-data-client --token --endpoint device-types --application-id ``` ### List recent versions (filtered by device type) ```bash ulogger-data-client --token --endpoint artifact-versions --application-id --device-type --limit 10 ``` ### List recent versions (all device types) ```bash ulogger-data-client --token --endpoint artifact-versions --application-id --limit 10 ``` ### Create deployment (all defaults) ```bash ulogger-data-client --token --create-deployment \ --application-id \ --device-type \ --version ``` ### Create deployment (custom options) ```bash ulogger-data-client --token --create-deployment \ --application-id \ --device-type \ --version \ --phase 2 \ --timeout-hours 24 \ --auto-advance=true \ --notes "Canary rollout for battery fix" ``` ## Parameter guidance ### Phase (1-10) - **Phase 1**: Canary — deploy to a small subset of devices - **Phase 5**: ~50% rollout - **Phase 10**: Full fleet deployment - Default to phase 1 unless the user explicitly requests broader rollout ### Timeout - Default: 6 hours - Use longer timeouts (24-48h) for phased rollouts where you expect devices to connect intermittently - Maximum: 168 hours (7 days) - Minimum: 1 hour ### Auto-advance - **Disabled (default)**: Deployment stays at current phase until manually advanced or expired - **Enabled**: Automatically promotes to next phase when current phase succeeds - Only enable if the user explicitly requests it ## Deployment error handling | HTTP Status | Meaning | Action | |-------------|---------|--------| | 201 | Success | Report deployment_id | | 400 | Validation error | Show error message, fix the invalid parameter | | 401 | Auth failure | Check token or certificate validity | | 409 | Conflict | Active deployment exists for same device_type + phase | | 502 | Database error | Retry or escalate | --- # Part 3: Certificate Bundle & Project Integration ## Goal Help users download their certificate bundle and integrate uLogger into their projects (Python applications or embedded C/C++ firmware). The certificate bundle is generated during account creation and contains device certificates, keys, and integration files. ## Required inputs - **API token** (`--token` or `ULOGGER_API_TOKEN` env var) — recommended, or - **Certificate** (`--cert`) and **private key** (`--key`) — for mTLS auth ## Optional inputs - **Output directory** (`--output-dir`, default: current directory) - **Project type** (`--project-type`: `python`, `embedded`, or `all`) ## Bundle contents The certificate zip contains these files: | File | Purpose | |------|---------| | `certificate.pem.crt` | Device X.509 certificate for mTLS | | `private.pem.key` | Device private key | | `ulogger_CA.pem.crt` | CA certificate chain | | `ulogger_certs_keys.h` | C/C++ header with certificates as char arrays | | `endpoint.txt` | MQTT broker endpoint (`mqtt.ulogger.ai`) | | `thing_name.txt` | IoT Core thing name | | `readme.txt` | Usage instructions | ## Command recipes ### Download certificate bundle zip ```bash ulogger-data-client --token --download-certs ``` Downloads `cert_.zip` to the current directory. ### Extract all files ```bash ulogger-data-client --token --extract-certs --output-dir ./certs ``` ### Extract for Python project only ```bash ulogger-data-client --token --extract-certs --output-dir ./certs --project-type python ``` Extracts: `certificate.pem.crt`, `private.pem.key`, `ulogger_CA.pem.crt`, `endpoint.txt`, `thing_name.txt`, `readme.txt` ### Extract for embedded C/C++ project only ```bash ulogger-data-client --token --extract-certs --output-dir ./certs --project-type embedded ``` Extracts: `ulogger_certs_keys.h`, `endpoint.txt`, `thing_name.txt`, `readme.txt` ## Python integration workflow After extracting certificates with `--project-type python`: 1. Install the ulogger-cloud package: ```bash pip install ulogger-cloud ``` 2. Add `ulogger-cloud` to `requirements.txt` if it exists. 3. Use the certificates in Python code: ```python from pathlib import Path from ulogger_cloud import MqttConfig, DeviceInfo, get_session_token mqtt_cfg = MqttConfig( cert_file=Path("./certs/certificate.pem.crt"), key_file=Path("./certs/private.pem.key"), customer_id=YOUR_CUSTOMER_ID, ) device = DeviceInfo(application_id=YOUR_APP_ID, device_serial="1") token = get_session_token(mqtt_cfg, device) ``` 4. For mTLS API access: ```python import requests resp = requests.get( "https://data-api.ulogger.ai/logs", cert=("./certs/certificate.pem.crt", "./certs/private.pem.key"), params={"start": "1h"}, ) ``` ## Embedded C/C++ integration workflow After extracting certificates with `--project-type embedded`: 1. Copy `ulogger_certs_keys.h` into your project's source tree. 2. Include the header in your TLS setup code: ```c #include "ulogger_certs_keys.h" ``` 3. Available symbols (all PEM-encoded, null-terminated char arrays): - `ulogger_user_certificate` — device certificate - `ulogger_user_private_key` — device private key - `ulogger_CA_certificate` — CA certificate 4. Add the uLogger embedded agent static library to your project. The library and integration instructions are at: - **Library & docs**: https://github.com/ulogger-ai/embedded_agent 5. Follow the example integrations for your connectivity type: - **Wi-Fi**: https://github.com/ulogger-ai/example-wifi-demo - **Bluetooth / Zigbee / Matter**: https://github.com/ulogger-ai/example-bluetooth-demo 6. Connect to `mqtt.ulogger.ai:8883` using mutual TLS with these credentials. ## Error handling | HTTP Status | Meaning | Action | |-------------|---------|--------| | 200 | Success | Download URL returned | | 401 | Auth failure | Check token or certificate validity | | 404 | Not found | Certificate bundle does not exist for this account | | 502 | S3 error | Retry or escalate |