iarv/mc-webui
1
0
Fork 1
mirror of https://github.com/MarekWo/mc-webui.git synced 2026-03-28 17:42:45 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
c7163aa0352343a4fbf0bf91ed1f10c293c400a4
mc-webui/technotes/API-Diagnostic-Commands.md
MarekWo e9e04fb22d docs: Add comprehensive API diagnostic commands cheatsheet 
Added technotes/API-Diagnostic-Commands.md with:
- Complete curl examples for all API endpoints
- SSH + docker exec one-liners for easy testing
- Organized by category (health, contacts, device, channels, messages, DM, settings, archives)
- Example JSON responses for each endpoint
- Useful one-liners with jq for advanced queries
- Quick troubleshooting section with logs and health checks
- Notes on ports, methods, and response times

This serves as a quick reference for debugging and testing the mc-webui API.
2025-12-29 16:09:00 +01:00

13 KiB
Raw Blame History

API Diagnostic Commands - Quick Reference

Server: 192.168.1.2 SSH: ssh mcwebui@192.168.1.2

NOTE: Replace the above example with your own server and credentials.

This cheatsheet contains useful commands for diagnosing mc-webui and meshcore-bridge using API endpoints.

Table of Contents

  1. Health Checks
  2. Contact Management
  3. Device Information
  4. Channel Management
  5. Messages
  6. Direct Messages (DM)
  7. Settings
  8. Archives

Health Checks

Check meshcore-bridge health

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://meshcore-bridge:5001/health | jq"

Response:

{
  "status": "healthy",
  "serial_port": "/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00",
  "advert_log": "/root/.config/meshcore/MarWoj.adverts.jsonl"
}

Check mc-webui connection status

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/status | jq"

Response:

{
  "success": true,
  "connected": true
}

Contact Management

Get all contacts (CLI type only, names only)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts | jq"

Response:

{
  "success": true,
  "count": 19,
  "contacts": [
    "SP7UNR_tdeck",
    "Kosu 🦜",
    "Arek",
    "daniel5120 🔫",
    "Szczwany-lis🦊"
  ]
}

Get detailed contacts (all types with metadata + last_seen)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/detailed | jq"

Response:

{
  "success": true,
  "count": 263,
  "limit": 350,
  "contacts": [
    {
      "name": "TK Zalesie Test 🦜",
      "public_key_prefix": "df2027d3f2ef",
      "type_label": "REP",
      "path_or_mode": "Flood",
      "last_seen": 1735429453,
      "raw_line": "TK Zalesie Test 🦜              REP   df2027d3f2ef  Flood"
    },
    {
      "name": "KRA C",
      "public_key_prefix": "d103df18e0ff",
      "type_label": "REP",
      "path_or_mode": "Flood",
      "last_seen": 1716206073
    }
  ]
}

Get pending contacts (awaiting manual approval)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://meshcore-bridge:5001/pending_contacts | jq"

Response:

{
  "success": true,
  "pending": [
    {
      "name": "C3396B62",
      "public_key": "c3396b628ba34b96138d962fda81e5e5450be14fa212793d55c71fba967a6262"
    }
  ],
  "raw_stdout": "MarWoj|* pending_contacts\nMarWoj|* \n           C3396B62: c3396b628ba34b96138d962fda81e5e5450be14fa212793d55c71fba967a6262"
}

Or via mc-webui API:

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/pending | jq"

Delete a contact (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/contacts/delete \
  -H 'Content-Type: application/json' \
  -d '{\"selector\": \"df2027d3f2ef\"}' | jq"

Response:

{
  "success": true,
  "message": "Contact removed successfully"
}

Approve pending contact (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/contacts/pending/approve \
  -H 'Content-Type: application/json' \
  -d '{\"public_key\": \"c3396b628ba34b96138d962fda81e5e5450be14fa212793d55c71fba967a6262\"}' | jq"

Response:

{
  "success": true,
  "message": "Contact approved successfully"
}

Device Information

Get device info

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/device/info | jq"

Response:

{
  "success": true,
  "info": {
    "device_name": "MarWoj",
    "public_key": "11009cebbd2744d33c94b980b8f2475241fd2ca6165bd623e5ef00ec6982be6a...",
    "battery": "100%",
    "voltage": "4.20V"
  }
}

Get device settings (persistent)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/device/settings | jq"

Response:

{
  "success": true,
  "settings": {
    "manual_add_contacts": false
  }
}

Update device settings (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/device/settings \
  -H 'Content-Type: application/json' \
  -d '{\"manual_add_contacts\": true}' | jq"

Response:

{
  "success": true,
  "message": "manual_add_contacts set to on",
  "settings": {
    "manual_add_contacts": true
  }
}

Channel Management

List all channels

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/channels | jq"

Response:

{
  "success": true,
  "channels": [
    {
      "index": 0,
      "name": "Public",
      "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    {
      "index": 1,
      "name": "Malopolska",
      "key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
    }
  ]
}

Get channel QR code (JSON format)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/channels/1/qr?format=json' | jq"

Response:

{
  "success": true,
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "channel": {
    "index": 1,
    "name": "Malopolska",
    "key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  }
}

Create new channel (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/channels \
  -H 'Content-Type: application/json' \
  -d '{\"name\": \"TestChannel\"}' | jq"

Response:

{
  "success": true,
  "message": "Channel created successfully",
  "channel": {
    "index": 2,
    "name": "TestChannel",
    "key": "auto-generated-key-here"
  }
}

Delete channel (DELETE request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X DELETE \
  http://192.168.1.2:5000/api/channels/2 | jq"

Response:

{
  "success": true,
  "message": "Channel removed successfully"
}

Messages

Get messages for current channel

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/messages | jq"

Response:

{
  "success": true,
  "messages": [
    {
      "timestamp": 1735430000,
      "sender": "Kosu 🦜",
      "text": "Hello from mesh!",
      "type": "CHAN",
      "channel_idx": 1
    }
  ],
  "count": 1
}

Get messages for specific channel

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages?channel_idx=1' | jq"

Get archived messages for specific date

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages?archive_date=2025-12-28&channel_idx=1' | jq"

Send message (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/messages \
  -H 'Content-Type: application/json' \
  -d '{\"text\": \"Test message\", \"channel_idx\": 1}' | jq"

Response:

{
  "success": true,
  "message": "Message sent successfully"
}

Check for new messages (smart refresh)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages/updates?last_seen={\"0\":1735430000,\"1\":1735429000}' | jq"

Response:

{
  "success": true,
  "updates": {
    "0": {
      "has_new": false,
      "unread_count": 0
    },
    "1": {
      "has_new": true,
      "unread_count": 3
    }
  },
  "total_unread": 3
}

Direct Messages (DM)

List DM conversations

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/dm/conversations | jq"

Response:

{
  "success": true,
  "conversations": [
    {
      "conversation_id": "kosu_🦜",
      "display_name": "Kosu 🦜",
      "last_message_time": 1735430000,
      "unread_count": 2
    }
  ]
}

Get DM messages for specific conversation

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/dm/messages?conversation_id=kosu_🦜&limit=50' | jq"

Response:

{
  "success": true,
  "messages": [
    {
      "timestamp": 1735430000,
      "sender": "Kosu 🦜",
      "recipient": "MarWoj",
      "text": "Private message text",
      "type": "PRIV",
      "pubkey_prefix": "df2027"
    }
  ]
}

Send DM (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/dm/messages \
  -H 'Content-Type: application/json' \
  -d '{\"recipient\": \"Kosu 🦜\", \"text\": \"Test DM\"}' | jq"

Response:

{
  "success": true,
  "message": "DM sent successfully"
}

Settings

Trigger sync (force message refresh)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST http://192.168.1.2:5000/api/sync | jq"

Response:

{
  "success": true,
  "message": "Sync triggered successfully"
}

Send advert (normal)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/device/command \
  -H 'Content-Type: application/json' \
  -d '{\"command\": \"advert\"}' | jq"

Response:

{
  "success": true,
  "message": "Command executed successfully"
}

Send flood advert (use sparingly!)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
  http://192.168.1.2:5000/api/device/command \
  -H 'Content-Type: application/json' \
  -d '{\"command\": \"floodadv\"}' | jq"

Archives

List available archives

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/archives | jq"

Response:

{
  "success": true,
  "archives": [
    {
      "date": "2025-12-28",
      "display_date": "28 December 2025",
      "file_path": "/mnt/archive/meshcore/2025-12-28.msgs"
    },
    {
      "date": "2025-12-27",
      "display_date": "27 December 2025",
      "file_path": "/mnt/archive/meshcore/2025-12-27.msgs"
    }
  ]
}

Trigger manual archiving (POST request)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST http://192.168.1.2:5000/api/archive/trigger | jq"

Response:

{
  "success": true,
  "message": "Archive created successfully"
}

Useful One-Liners

Count contacts by type

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/detailed | jq '.contacts | group_by(.type_label) | map({type: .[0].type_label, count: length})'"

Response:

[
  {"type": "CLI", "count": 17},
  {"type": "REP", "count": 226},
  {"type": "ROOM", "count": 20}
]

Get only active contacts (last_seen < 1 hour)

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/detailed | jq --arg now \"\$(date +%s)\" '.contacts | map(select(.last_seen and (\$now | tonumber) - .last_seen < 3600))'"

Check total unread messages across all channels

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages/updates?last_seen={}' | jq '.total_unread'"

List pending contacts with full keys

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://meshcore-bridge:5001/pending_contacts | jq '.pending[] | {name, key: .public_key}'"

Quick Troubleshooting

Check if bridge is responding

ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -w '\nHTTP Status: %{http_code}\n' http://meshcore-bridge:5001/health"

Check if mc-webui is responding

ssh mcwebui@192.168.1.2 "curl -s -w '\nHTTP Status: %{http_code}\n' http://192.168.1.2:5000/api/status"

View recent bridge logs

ssh mcwebui@192.168.1.2 "docker logs --tail 50 meshcore-bridge"

View recent mc-webui logs

ssh mcwebui@192.168.1.2 "docker logs --tail 50 mc-webui"

Follow logs in real-time

ssh mcwebui@192.168.1.2 "docker logs -f mc-webui"

Check .msgs file size

ssh mcwebui@192.168.1.2 "ls -lh ~/.config/meshcore/MarWoj.msgs"

Check .adverts.jsonl file size

ssh mcwebui@192.168.1.2 "ls -lh ~/.config/meshcore/MarWoj.adverts.jsonl"

Notes

  • Port 5001 (meshcore-bridge): Internal only, accessible via docker exec mc-webui
  • Port 5000 (mc-webui): Publicly accessible on server
  • All POST/DELETE requests require Content-Type: application/json header
  • Use jq for pretty JSON formatting
  • For debugging, add -v flag to curl for verbose output
  • Response times should be < 500ms for most endpoints
  • Bridge health endpoint includes serial port and advert log paths

Last updated: 2025-12-29 mc-webui version: Contact Management MVP v2 with "Last Seen" feature

Reference in New Issue View Git Blame Copy Permalink