Skip to content

Commit c56e15a

Browse files
committed
Add documentation for node tag import feature
README.md: - Add "Node Tags" section with comprehensive documentation - Document CLI usage: meshcore-hub collector import-tags - Document Docker Compose usage: docker compose --profile import-tags - Document JSON format with field descriptions - Document import options (--no-create-nodes) - Document data directory structure for Docker - Document tag management via REST API (CRUD operations) AGENTS.md: - Add tag_import.py to project structure - Update example/data structure with collector/web subdirectories - Update data directory structure documentation
1 parent cbaf4f4 commit c56e15a

2 files changed

Lines changed: 106 additions & 1 deletion

File tree

AGENTS.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,7 @@ meshcore-hub/
249249
│ ├── collector/
250250
│ │ ├── cli.py
251251
│ │ ├── subscriber.py # MQTT subscriber
252+
│ │ ├── tag_import.py # Tag import from JSON
252253
│ │ ├── handlers/ # Event handlers
253254
│ │ └── webhook.py # Webhook dispatcher
254255
│ ├── api/
@@ -278,8 +279,13 @@ meshcore-hub/
278279
│ └── mosquitto.conf # MQTT broker configuration
279280
├── example/
280281
│ └── data/
281-
│ └── members.json # Example network members data
282+
│ ├── collector/
283+
│ │ └── tags.json # Example node tags data
284+
│ └── web/
285+
│ └── members.json # Example network members data
282286
├── data/ # Runtime data (gitignored)
287+
│ ├── collector/ # Collector data (tags.json)
288+
│ └── web/ # Web data (members.json)
283289
├── Dockerfile # Docker build configuration
284290
├── docker-compose.yml # Docker Compose services (gitignored)
285291
└── docker-compose.yml.example # Docker Compose template

README.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,9 @@ meshcore-hub interface --mode sender --mock # Use mock device
231231
# Collector component
232232
meshcore-hub collector --database-url sqlite:///./data.db
233233

234+
# Import node tags from JSON file
235+
meshcore-hub collector import-tags /path/to/tags.json
236+
234237
# API component
235238
meshcore-hub api --host 0.0.0.0 --port 8000
236239

@@ -243,6 +246,102 @@ meshcore-hub db downgrade # Rollback one migration
243246
meshcore-hub db current # Show current revision
244247
```
245248

249+
## Node Tags
250+
251+
Node tags allow you to attach custom metadata to nodes (e.g., location, role, owner). Tags are stored in the database and returned with node data via the API.
252+
253+
### Importing Tags from JSON
254+
255+
Tags can be bulk imported from a JSON file:
256+
257+
```bash
258+
# Native CLI
259+
meshcore-hub collector import-tags /path/to/tags.json
260+
261+
# With Docker Compose
262+
docker compose --profile import-tags run --rm import-tags
263+
```
264+
265+
### Tags JSON Format
266+
267+
```json
268+
{
269+
"tags": [
270+
{
271+
"public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
272+
"key": "location",
273+
"value": "San Francisco, CA",
274+
"value_type": "string"
275+
},
276+
{
277+
"public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
278+
"key": "altitude",
279+
"value": "150",
280+
"value_type": "number"
281+
}
282+
]
283+
}
284+
```
285+
286+
| Field | Required | Description |
287+
|-------|----------|-------------|
288+
| `public_key` | Yes | 64-character hex public key of the node |
289+
| `key` | Yes | Tag name (max 100 characters) |
290+
| `value` | No | Tag value (stored as text) |
291+
| `value_type` | No | Type hint: `string`, `number`, `boolean`, or `coordinate` (default: `string`) |
292+
293+
### Import Options
294+
295+
```bash
296+
# Create nodes if they don't exist (default behavior)
297+
meshcore-hub collector import-tags tags.json
298+
299+
# Skip tags for nodes that don't exist
300+
meshcore-hub collector import-tags --no-create-nodes tags.json
301+
```
302+
303+
### Data Directory Structure
304+
305+
For Docker deployments, organize your data files:
306+
307+
```
308+
data/
309+
├── collector/
310+
│ └── tags.json # Node tags for import
311+
└── web/
312+
└── members.json # Network members list
313+
```
314+
315+
Example files are provided in `example/data/`.
316+
317+
### Managing Tags via API
318+
319+
Tags can also be managed via the REST API:
320+
321+
```bash
322+
# List tags for a node
323+
curl http://localhost:8000/api/v1/nodes/{public_key}/tags
324+
325+
# Create a tag (requires admin key)
326+
curl -X POST \
327+
-H "Authorization: Bearer <API_ADMIN_KEY>" \
328+
-H "Content-Type: application/json" \
329+
-d '{"key": "location", "value": "Building A"}' \
330+
http://localhost:8000/api/v1/nodes/{public_key}/tags
331+
332+
# Update a tag
333+
curl -X PUT \
334+
-H "Authorization: Bearer <API_ADMIN_KEY>" \
335+
-H "Content-Type: application/json" \
336+
-d '{"value": "Building B"}' \
337+
http://localhost:8000/api/v1/nodes/{public_key}/tags/location
338+
339+
# Delete a tag
340+
curl -X DELETE \
341+
-H "Authorization: Bearer <API_ADMIN_KEY>" \
342+
http://localhost:8000/api/v1/nodes/{public_key}/tags/location
343+
```
344+
246345
## API Documentation
247346

248347
When running, the API provides interactive documentation at:

0 commit comments

Comments
 (0)