All guides

How-to guides · 5 min

Import and validate a profile

A device profile is declarative JSON with no code. Here you create a draft from an example or your own file, edit it, validate it, make a new version and bind it to a source.

Where to start

All of this happens on the Profile Studio panel in the workspace. Owners, Admins and Developers can edit and run tests.

ButtonWhat it does
Create reference draftCreates a ready BESS draft within the reference ceiling. The simplest start.
Create load reference draftDoes the same for a controllable load.
Import profile JSONPaste your own definition up to 64 KiB.

The easiest way to get valid JSON: create a reference draft, click “Export profile JSON” and adapt the file to your device.

lab-device-profile-1 (скорочено / shortened)
{
  "schema_version": "lab-device-profile-1",
  "profile_id": "WF-PROFILE-LAB-BATTERY-001",
  "profile_version": "0.1.0",
  "status": "DRAFT",
  "manufacturer": "Wesfin Lab",
  "model": "Deterministic reference BESS",
  "asset_type": "BATTERY",
  "supported_firmware": "1.0.0",
  "created_by": "...", "created_at": "...", "updated_at": "...",
  "connection": "SIMULATOR",
  "telemetry": [ ... ],
  "commands": { ... },
  "constraints": { ... },
  "safety": { ... },
  "flexibility": { ... },
  "evidence": ["ACKNOWLEDGED", "EXECUTED", "MEASURED", "RESTORE_EXECUTED", "RESTORED"],
  "tests": []
}

Import and edit

  1. Paste the JSON

    Expand “Import profile JSON”, paste the definition and click “Import as draft”. The bytes go to the server as they are, so it can reject duplicate keys and non-finite numbers.

  2. Open the draft

    The Lab opens the version page. At the top are the DRAFT state, the definition hash and the version_id.

  3. Edit

    In the “Profile editor” change the manufacturer, model, firmware, connector, limits, safety policy and flexibility. Edit telemetry, commands and test vectors in the “Full JSON definition” field.

  4. Save

    Click “Save draft”. Validation and tests use only the saved version; unsaved edits are not included.

Only a version in DRAFT or VALIDATION_FAILED can be edited. The asset type comes from the starting draft and cannot be changed in the editor.

Validation and tests

The “Validation and deterministic tests” panel shows the SCHEMA → SEMANTIC → SAFETY → EXECUTION stages and the “Blocking reasons” for each. Click “Validate saved version and run tests”. The Lab opens the test run page; the report appears when the run finishes.

If the run passes, the version becomes VALIDATED. If not, it becomes VALIDATION_FAILED and can be edited again. Only one run per version can be active at a time.

Tests run on the reference model and isolated connector fixtures. Other firmware and physical devices remain UNKNOWN.

A new version

A validated version cannot be changed. On the “New version and comparison” panel enter “New version (semver)”, for example 0.2.0, and click “Create derived draft”. The new draft remembers which version it came from.

In “Compare against version” pick another version. The change table marks each change as LOW, CONTROL_RELEVANT or SAFETY_RELEVANT. Changes in constraints and safety are always SAFETY_RELEVANT.

Binding to a source

  1. Open the source

    On the source page find the “Device profile version” panel.

  2. Choose the version

    The “Validated version” list holds only VALIDATED versions. The profile's asset type and connector must match the source.

  3. Bind

    Click “Bind validated version”. It needs a current PASS report, no active or unknown command, an idle state within the new limits, and revoked credentials.

Profile limits can only narrow the source's limits. Binding resets control and local write consent: an Owner/Admin must explicitly consent again. All of this applies to the Lab only.

Common problems

ReasonWhat to do
profile schema invalidImport was rejected: the JSON does not fit the schema, has an unknown field, a duplicate key, NaN or is over 64 KiB. Compare with an exported reference draft.
profile version identity already existsThis profile_id and profile_version already exist in the workspace. Change profile_version.
FIRMWARE_RANGE_EMPTYThe firmware range contradicts itself and contains no version.
SAFETY_TELEMETRY_MISSINGA battery needs asset_active_power_kw, soc_pct, available_charge_power_kw, available_discharge_power_kw. A load needs asset_active_power_kw, baseline_kw, power_floor_kw, power_cap_kw.
DUPLICATE_TELEMETRY_MAPPINGA field or source_key appears twice.
MAPPING_DIMENSION_MISMATCHA percent field is mapped to a non-percent key or the other way round.
PERCENT_MAPPING_INVALID_pct fields need unit %, scale 1 and sign 1.
POWER_MAPPING_UNIT_INVALIDOnly W and kW are allowed for power.
CONSTRAINT_ORDER_INVALIDsoc_min_pct must be below soc_max_pct and the duration no longer than the TTL. For a load: floor ≤ baseline ≤ cap.
FLEXIBILITY_EXCEEDS_DEVICE_LIMITFlexibility exceeds the device limits. Lower available_up_kw or available_down_kw.
HOME_ASSISTANT_MAPPING_CONNECTOR_MISMATCHhome_assistant_mapping is present but the connector is not HOME_ASSISTANT. Remove the mapping.
LOAD_BATTERY_TELEMETRY_FORBIDDENA load profile has battery fields (SOC, SOH, charge/discharge). Remove them.
UNSAFE_RECOVERY_POLICYrestore_power_kw must be 0 for a battery or minus the baseline for a load; replay_completed false; stale_policy and offline_policy REJECT.
DISTINCT_EVIDENCE_REQUIREDevidence must list all five: ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_EXECUTED, RESTORED.
PROTECTED_CONFIGURATION_WRITEWriting protected configuration is forbidden. Turn off protected_configuration_writable.
ttl_required, fail_closed, abort_restoresThese safety flags, as well as restore_after_ttl and restore_on_disconnect, must be true.