All guides

Reference · 8 min

Device profile fields

The full list of lab-device-profile-1 fields: what each one means, its limits and how to fix validation errors.

General rules

A profile is data only. It holds no addresses, passwords, scripts or code. An unknown field is a schema error.

File limits: up to 64 KiB of canonical JSON, no repeated keys, no NaN or Infinity. Write numbers as JSON numbers, not strings. true and false go without quotes. An integer field does not accept 60.0.

Validation has four stages: SCHEMA, SEMANTIC, SAFETY and EXECUTION. Each reports on its own. Tests run only when SCHEMA and SEMANTIC have passed.

The global Lab ceiling: 10 kW, 20 kWh, SOC 10–95%, TTL up to 60 seconds, freshness up to 30 seconds. A profile can only narrow these limits.

Identity and version

FieldMeaning and limits
schema_versionAlways "lab-device-profile-1".
profile_idCapital Latin letters, digits and hyphens. Starts with a letter. 3 to 128 characters.
profile_versionVersion X.Y.Z, optionally with a suffix such as 1.2.0-beta.1. Up to 64 characters.
statusDRAFT, VALIDATING, VALIDATED or VALIDATION_FAILED.
manufacturer, modelManufacturer and model. 1 to 128 characters.
descriptionOptional. Up to 2000 characters.
asset_typeBATTERY, CONTROLLABLE_LOAD, EV_CHARGER or GENERIC_GENERATOR. Test packs exist only for BATTERY and CONTROLLABLE_LOAD.
supported_firmwareConditions separated by spaces, all must hold: ">=1.0.0 <2.0.0". Operators >=, <=, >, <, =. Up to 256 characters.
created_byAuthor. 1 to 128 characters.
created_at, updated_atISO 8601 date and time with a time zone.

The definition hash leaves out status and updated_at. Empty optional fields are left out too. So a status change does not change the hash.

The Lab tests only reference firmware 1.0.0. If your range does not include it, the report gets the blocker REFERENCE_FIRMWARE_OUTSIDE_DECLARED_RANGE. Other firmware versions show as UNKNOWN in the report.

Connection

FieldMeaning and limits
connectionSIMULATOR, MQTT or HOME_ASSISTANT.
home_assistant_mappingRequired for HOME_ASSISTANT and forbidden for the others. It lists HA entities: active_power, soc, soh, available_charge, available_discharge, grid_power, site_load, online, fault, write_consent, sample_timestamp, write_target, write_unit, write_sign, freshness_seconds.

The HA mapping holds no token or URL. write_target cannot be the same entity as active_power: the measurement must be independent.

CONTROLLABLE_LOAD over HOME_ASSISTANT is not qualified yet. Such a profile fails validation. Use SIMULATOR or MQTT for loads.

Telemetry

telemetry is a list of 1 to 7 mappings. Each one says how a device value becomes a canonical Lab field.

FieldMeaning and limits
fieldCanonical field: asset_active_power_kw, soc_pct, soh_pct, available_charge_power_kw, available_discharge_power_kw, grid_active_power_kw, site_load_kw, baseline_kw, power_floor_kw, power_cap_kw.
source_keyThe key in the device data. It accepts the same canonical names.
unitW, kW or %. A value in W is divided by 1000.
scaleA multiplier, above 0 and at most 1000. Default 1.
signThe integer 1 or -1. Default 1. Flips the sign if the device counts the other way.

Signs in the Lab: asset power is positive when discharging and negative when charging. Grid power is positive on import and negative on export. Load consumption is negative power.

Required fields for BATTERY: asset_active_power_kw, soc_pct, available_charge_power_kw, available_discharge_power_kw. For CONTROLLABLE_LOAD: asset_active_power_kw, baseline_kw, power_floor_kw, power_cap_kw. A load cannot have SOC, SOH or available charge and discharge power.

Commands

FieldMeaning and limits
typesExactly ["SET_ACTIVE_POWER"].
writableExactly ["asset_active_power_kw"].
target_field"asset_active_power_kw".
protected_configuration_writableDefault false. The value true fails SAFETY.

Constraints: battery

FieldMeaning and limits
max_charge_kw, max_discharge_kwAbove 0, at most 10.
capacity_kwhAbove 0, at most 20.
soc_min_pct, soc_max_pct10 to 95. The minimum must be below the maximum.
max_duration_seconds1 to 60. No more than max_ttl_seconds.
max_ttl_seconds1 to 60.
freshness_seconds1 to 30. Older data blocks commands.
baseline_kwOptional, -10 to 10, default 0.
minimum_on_seconds, minimum_off_secondsOptional, 0 to 60, default 0.

Constraints: controllable load

For CONTROLLABLE_LOAD, constraints has a different set of fields. All are required. Powers here are positive consumption amounts in kW.

FieldMeaning and limits
baseline_kw0 to 10. Usual consumption without a command.
power_floor_kw0 to 10. The lowest allowed consumption.
power_cap_kwAbove 0, at most 10. The highest allowed consumption.
max_duration_seconds, max_ttl_seconds1 to 60. Duration no more than TTL.
freshness_seconds1 to 30.
minimum_on_seconds, minimum_off_seconds0 to 60. How many seconds the load must stay on or off before it switches.

power_floor_kw <= baseline_kw <= power_cap_kw must hold. Battery fields such as capacity_kwh or soc_min_pct are forbidden here.

Safety

FieldMeaning and limits
ttl_required, fail_closedMust be true.
restore_after_ttl, restore_on_disconnect, abort_restoresMust be true: restore after TTL, on disconnect and on abort.
replay_completedMust be false. A completed command is never replayed.
restore_power_kw-10 to 10. For a battery, 0. For a load, equal to -baseline_kw.
stale_policy, offline_policyREJECT or IGNORE. Only REJECT passes.

Flexibility and evidence

FieldMeaning and limits
available_up_kw0 to 10. Battery: no more than max_discharge_kw. Load: no more than baseline_kw - power_floor_kw.
available_down_kw0 to 10. Battery: no more than max_charge_kw. Load: no more than power_cap_kw - baseline_kw.
response_time_msAn integer from 0 to 3000.
evidenceA list of all five stages: ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_EXECUTED, RESTORED.

Custom test vectors

tests holds up to 32 vectors. They are added to the standard pack. In the report a vector is named custom_<vector_id>. A run has at most 96 tests in total.

FieldMeaning and limits
schema_version"lab-test-vector-1".
vector_idLowercase Latin letters, digits and _. Starts with a letter, up to 64 characters. Unique.
vector_versionVersion X.Y.Z.
target_kw-100 to 100. Beyond ±10 kW the command is rejected, so expect REJECTED.
duration_seconds1 to 60.
ttl_seconds0 to 60. The value 0 gives an already expired command.
faultNONE or one fault: INTERNET_DISCONNECT, CONNECTOR_DISCONNECT, TELEMETRY_TIMEOUT, STALE_TIMESTAMP, MALFORMED_TELEMETRY, OUT_OF_RANGE_TELEMETRY, DEVICE_FAULT, METER_UNAVAILABLE, ACK_TIMEOUT, EXECUTION_TIMEOUT, RECONNECT, DUPLICATE_ACK, DELAYED_TELEMETRY, CLOCK_SKEW.
expected_statusRESTORED, REJECTED, EXPIRED or UNKNOWN.
initial_soc_pctBattery only, and required there. 10 to 95. Forbidden in a load vector.
tests[0] · BATTERY
{
  "schema_version": "lab-test-vector-1",
  "vector_id": "short_discharge",
  "vector_version": "1.0.0",
  "target_kw": 2,
  "duration_seconds": 10,
  "ttl_seconds": 30,
  "fault": "NONE",
  "expected_status": "RESTORED",
  "initial_soc_pct": 50
}

Example

This is the Lab's reference battery profile. It is for learning and does not describe a real product.

lab-device-profile-1 · BATTERY
{
  "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": "lab-author",
  "created_at": "2026-10-20T09:00:00+00:00",
  "updated_at": "2026-10-20T09:00:00+00:00",
  "connection": "SIMULATOR",
  "telemetry": [
    {"field": "asset_active_power_kw", "source_key": "asset_active_power_kw", "unit": "kW"},
    {"field": "soc_pct", "source_key": "soc_pct", "unit": "%"},
    {"field": "soh_pct", "source_key": "soh_pct", "unit": "%"},
    {"field": "available_charge_power_kw", "source_key": "available_charge_power_kw", "unit": "kW"},
    {"field": "available_discharge_power_kw", "source_key": "available_discharge_power_kw", "unit": "kW"},
    {"field": "grid_active_power_kw", "source_key": "grid_active_power_kw", "unit": "kW"},
    {"field": "site_load_kw", "source_key": "site_load_kw", "unit": "kW"}
  ],
  "commands": {"types": ["SET_ACTIVE_POWER"], "writable": ["asset_active_power_kw"], "target_field": "asset_active_power_kw"},
  "constraints": {"max_charge_kw": 10, "max_discharge_kw": 10, "capacity_kwh": 20,
    "soc_min_pct": 10, "soc_max_pct": 95, "max_duration_seconds": 60,
    "max_ttl_seconds": 60, "freshness_seconds": 30},
  "safety": {"ttl_required": true, "fail_closed": true, "restore_after_ttl": true,
    "restore_on_disconnect": true, "abort_restores": true, "replay_completed": false,
    "restore_power_kw": 0, "stale_policy": "REJECT", "offline_policy": "REJECT"},
  "flexibility": {"available_up_kw": 10, "available_down_kw": 10, "response_time_ms": 1000},
  "evidence": ["ACKNOWLEDGED", "EXECUTED", "MEASURED", "RESTORE_EXECUTED", "RESTORED"],
  "tests": []
}

For a load, the type, telemetry, constraints, restore power and flexibility change:

CONTROLLABLE_LOAD
"asset_type": "CONTROLLABLE_LOAD",
"telemetry": [
  {"field": "asset_active_power_kw", "source_key": "asset_active_power_kw", "unit": "kW"},
  {"field": "baseline_kw", "source_key": "baseline_kw", "unit": "kW"},
  {"field": "power_floor_kw", "source_key": "power_floor_kw", "unit": "kW"},
  {"field": "power_cap_kw", "source_key": "power_cap_kw", "unit": "kW"}
],
"constraints": {"baseline_kw": 5, "power_floor_kw": 0, "power_cap_kw": 10,
  "max_duration_seconds": 60, "max_ttl_seconds": 60, "freshness_seconds": 30,
  "minimum_on_seconds": 2, "minimum_off_seconds": 2},
"safety": { ... "restore_power_kw": -5 ... },
"flexibility": {"available_up_kw": 5, "available_down_kw": 5, "response_time_ms": 1000}

Validation errors

SCHEMA shows the field path and an error type, such as missing, extra_forbidden, literal_error, string_pattern_mismatch or less_than_equal. Up to 32 errors are shown. A mismatch between asset type and constraints or vectors also fails here, with the type value_error.

CodeWhat to fix
INVALID_PROFILE_DATAThe file does not parse as JSON, is over 64 KiB, has a repeated key or NaN. Fix the JSON itself.
FIRMWARE_RANGE_EMPTYNo version satisfies all supported_firmware conditions. Widen the range.
HOME_ASSISTANT_MAPPING_REQUIREDAdd home_assistant_mapping or change connection.
HOME_ASSISTANT_MAPPING_CONNECTOR_MISMATCHRemove home_assistant_mapping: it is for HOME_ASSISTANT only.
DUPLICATE_TELEMETRY_MAPPINGEach field and each source_key may appear only once.
SAFETY_TELEMETRY_MISSINGAdd the required telemetry fields for your asset type.
LOAD_BATTERY_TELEMETRY_FORBIDDENRemove soc_pct, soh_pct and available charge and discharge power from a load.
LOAD_HOME_ASSISTANT_NOT_QUALIFIEDChoose SIMULATOR or MQTT for a load.
MAPPING_DIMENSION_MISMATCHA percentage maps only to a percentage, power only to power.
PERCENT_MAPPING_INVALIDFor _pct fields: unit "%", scale 1, sign 1.
POWER_MAPPING_UNIT_INVALIDFor power fields, unit must be W or kW.
CONSTRAINT_ORDER_INVALIDCheck: soc_min_pct < soc_max_pct, duration <= TTL, power_floor_kw <= baseline_kw <= power_cap_kw.
FLEXIBILITY_EXCEEDS_DEVICE_LIMITReduce available_up_kw or available_down_kw to the device limits.
DUPLICATE_TEST_VECTORGive each vector its own vector_id.
ttl_required, fail_closed, restore_after_ttl, restore_on_disconnect, abort_restoresSAFETY names the field that is not true. Set it to true.
UNSAFE_RECOVERY_POLICYreplay_completed false, both policies REJECT, restore_power_kw 0 for a battery or -baseline_kw for a load.
PROTECTED_CONFIGURATION_WRITESet protected_configuration_writable to false.
DISTINCT_EVIDENCE_REQUIREDList all five stages in evidence.
ASSET_TYPE_PACK_NOT_QUALIFIEDEV_CHARGER and GENERIC_GENERATOR have no test pack yet. The profile cannot become VALIDATED.
REFERENCE_FIRMWARE_OUTSIDE_DECLARED_RANGEInclude 1.0.0 in supported_firmware.

If a test fails in EXECUTION, the test name becomes a blocker. Open it in the report: it shows the inputs, the expectation, the observation and the reason.