Skip to content

CONFIGURATION.md

Latest commit

 

History

History
138 lines (106 loc) · 6.21 KB

CONFIGURATION.md

File metadata and controls

138 lines (106 loc) · 6.21 KB
Raw

SCIoT Configuration Guide

SCIoT now validates the primary server and static HTTP client YAML files before startup. Invalid values fail with field-level errors such as communication.http.port: must be between 1 and 65535.

Canonical files

  • Server runtime: src/server/settings.yaml
  • Static HTTP client runtime: src/client/python/http_config.yaml
  • Server examples: docs/config/server.minimal.yaml, docs/config/server.full.yaml
  • Static client examples: docs/config/client-http.minimal.yaml, docs/config/client-http.full.yaml

src/server/client_config.yaml is retained as legacy reference material. New runtime changes should use src/server/settings.yaml for server configuration and src/client/python/http_config.yaml for static-client configuration.

Override precedence

For current supported paths, settings are resolved in this order:

  1. Explicit CLI arguments, where available. For example, sciot-client --config src/client/python/http_config.yaml --device-id DEVICE_ID --max-cycles 1.
  2. Environment variables.
  3. YAML file values.

Supported environment overrides:

  • SCIOT_TRANSPORTS: comma-separated server transports, for example http,mqtt.
  • SCIOT_SERVER_HOST: server HTTP host for the server, or server host used by the static client.
  • SCIOT_SERVER_PORT: server HTTP port for the server, or server port used by the static client.
  • SCIOT_HTTP_MODEL: model key used by the server HTTP transport.
  • SCIOT_VERBOSE: true or false server verbosity.
  • SCIOT_CLIENT_DEVICE_ID: static-client device ID.
  • SCIOT_CLIENT_MAX_CYCLES: bounded client cycle count.
  • SCIOT_CLIENT_RUN_DURATION_SECONDS: bounded client run duration.

Validated fields

Server validation covers:

  • enabled transports in communication.mode;
  • HTTP/WebSocket/MQTT hostnames, ports, endpoints/topics, NTP server names, and model references;
  • model dimensions, split-layer limits, and model directories;
  • local-inference probability in the inclusive range 0.0..1.0;
  • delay sections and delay distributions;
  • boolean flags such as verbose, debug_cprofiler, compression, and input saving;
  • evaluation.split.max_rows and evaluation.split.interval_minutes (non-negative);
  • evaluation.outputs.inference_cycles and evaluation.outputs.offloading_decisions (booleans);
  • optional Firestore telemetry publishing under evaluation.firestore.

Evaluation outputs

The server writes inference-cycle CSV output under data/results/evaluations/inference_cycles_*.csv. Each offloading decision is mirrored to both CSV and JSONL:

  • data/results/offloading_decisions*.csv
  • data/results/offloading_decisions_<inference_timestamp>.jsonl

Each output stream can be enabled or disabled as needed (both default to true); a disabled stream skips its event construction entirely, so there is no runtime cost. Stable scalar metrics are emitted as normal CSV columns; variable-length values such as per-layer timing lists and offloading candidates are preserved as JSON-encoded CSV cells and as native JSON values in JSONL:

evaluation:
  outputs:
    inference_cycles: true       # inference_cycles_*.csv (structured evaluation)
    offloading_decisions: true   # decision CSV and inference-timestamped JSONL mirror

Splitting

Instead of a single CSV file with size-based rotation (which discards old data), CSV outputs are split into never-deleted segment files:

evaluation:
  split:
    max_rows: 5000        # open a new segment every N rows (0 = disabled)
    interval_minutes: 30  # open a new segment every T minutes (0 = disabled)

A new CSV segment is opened at the first criterion that trips. CSV segment filenames embed a zero-padded index and segment start time, e.g. offloading_decisions.seg0001_20260706_101500.csv. The JSONL mirror does not use CSV-style segments: every offloading decision uses its own inference decision timestamp directly in the filename: offloading_decisions_20260706_101500.jsonl. Fractional seconds are added only if two decisions have the same second-level inference timestamp.

Firestore publishing

Local CSV output remains the primary runtime artifact. Optionally, the server can also queue each telemetry row for Cloud Firestore publishing in the background:

evaluation:
  firestore:
    enabled: false
    project_id: null          # Application Default Credentials project if null
    database: null            # default Firestore database if null
    credentials_path: null    # optional service-account JSON path
    collection: sciot_results
    run_document: null        # defaults to the compact server-start timestamp
    publish_inference_cycles: true
    publish_offloading_decisions: true
    flush_interval_seconds: 300

The Firestore client is part of the server runtime profile. Install the server with uv sync --extra server. Documents are written below:

  • sciot_results/{run_document}/inference_cycles/{document_id}
  • sciot_results/{run_document}/offloading_decisions/{document_id}

For offloading decisions, the Firestore document id and payload reference the same inference-timestamped JSONL file written locally, such as offloading_decisions_20260630_105214.jsonl, via offloading_decisions_jsonl_file and offloading_decisions_jsonl_path.

Publishing is buffered and best-effort: local CSV files are written immediately, then queued Firestore rows are flushed every flush_interval_seconds seconds (five minutes by default). Firestore errors are logged and do not stop local CSV writes or inference.

Static-client validation covers:

  • client identity and lifecycle limits;
  • server host/port and endpoint paths;
  • model image, input size, split layer, TFLite directory, and submodel prefix;
  • delay sections and distributions;
  • local-inference probability and boolean flags.

Migration notes

  • Do not keep edited runtime copies as committed .backup files. The checked-in .backup configuration files were removed; use Git history or files outside the repository for local snapshots.
  • Use the example files under docs/config/ when creating new deployments.
  • Prefer environment variables for temporary host, port, model, and bounded-run overrides.
  • Add new configuration keys to src/sciot/config.py and include valid/invalid tests before using them in runtime code.