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.
| Button | What it does |
|---|---|
| Create reference draft | Creates a ready BESS draft within the reference ceiling. The simplest start. |
| Create load reference draft | Does the same for a controllable load. |
| Import profile JSON | Paste 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.
{
"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
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.
Open the draft
The Lab opens the version page. At the top are the DRAFT state, the definition hash and the version_id.
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.
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
Open the source
On the source page find the “Device profile version” panel.
Choose the version
The “Validated version” list holds only VALIDATED versions. The profile's asset type and connector must match the source.
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
| Reason | What to do |
|---|---|
| profile schema invalid | Import 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 exists | This profile_id and profile_version already exist in the workspace. Change profile_version. |
| FIRMWARE_RANGE_EMPTY | The firmware range contradicts itself and contains no version. |
| SAFETY_TELEMETRY_MISSING | A 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_MAPPING | A field or source_key appears twice. |
| MAPPING_DIMENSION_MISMATCH | A 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_INVALID | Only W and kW are allowed for power. |
| CONSTRAINT_ORDER_INVALID | soc_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_LIMIT | Flexibility exceeds the device limits. Lower available_up_kw or available_down_kw. |
| HOME_ASSISTANT_MAPPING_CONNECTOR_MISMATCH | home_assistant_mapping is present but the connector is not HOME_ASSISTANT. Remove the mapping. |
| LOAD_BATTERY_TELEMETRY_FORBIDDEN | A load profile has battery fields (SOC, SOH, charge/discharge). Remove them. |
| UNSAFE_RECOVERY_POLICY | restore_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_REQUIRED | evidence must list all five: ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_EXECUTED, RESTORED. |
| PROTECTED_CONFIGURATION_WRITE | Writing protected configuration is forbidden. Turn off protected_configuration_writable. |
| ttl_required, fail_closed, abort_restores | These safety flags, as well as restore_after_ttl and restore_on_disconnect, must be true. |