openapi: 3.2.0 info: title: Gridx Ai Scan API version: 2.0.0 contact: name: gridX url: https://www.gridx.ai/module/api email: developer-community@gridx.de license: name: All rights reserved. url: https://www.gridx.ai/ x-api-id: ba9d6a25-ae1a-4ac8-af7a-70b76db17021 x-audience: public-external description: 'Operations tagged Scan across 2 of this provider''s published API definitions: gridx-api.json, gridx-ai-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.gridx.de description: Production tags: - name: Scan x-displayName: Scan paths: /gateways/{gatewayID}/scans: get: operationId: listGatewayScans summary: List Gateway's Scans description: 'List of scans for the given gateway and the given interval. If no interval is specified, the entire period is considered and all scans are listed.' tags: - Scan parameters: - name: gatewayID description: 'Unique identifier used to access a gateway. ' in: path required: true schema: type: string format: uuid example: 4ef41512-8445-4b90-aa53-8f8549b3f4bd - name: interval description: 'Requested time interval, formatted in ISO8601. In this format the start and end point of the interval are formatted according to RFC3339 and separated by a slash "/". ' in: query required: true allowReserved: true example: 2021-12-24T18:21:00Z/2021-12-25T18:21:00Z schema: type: string format: datetime - name: page description: 'Requested page, to be used in combination with the `per_page` parameter. ' in: query schema: type: integer format: int32 default: 1 minimum: 1 example: 1 - name: per_page description: 'Requested number of items per page. ' in: query schema: type: integer format: int32 default: 20 minimum: 20 maximum: 500 example: 10 - name: sort description: 'The field to sort the results by, to be used in combination with the `order` parameter. Defaults to `finished`. ' in: query schema: type: string enum: - started - finished default: finished example: started - name: order description: 'Order direction of the results, to be used in combination with the `sort` parameter. Defaults to `asc`. ' in: query schema: type: string enum: - asc - desc default: asc example: desc responses: '200': description: 'An array of scans, sorted by `sort` and `order`. ' content: application/vnd.gridx.v2+json: schema: type: - array - 'null' items: title: Scan description: Represents a group of scanners than have to run on a specific gridbox. type: object properties: id: description: Unique identifier of a scan. type: string format: uuid example: 9ee88ee2-49f4-434d-a96f-67aca96aaa0a startedAt: description: The time at which the scan has started. type: string format: date-time readOnly: true example: '2018-04-15T00:00:00Z' finishedAt: description: The time at which the scan has finished. type: string format: date-time readOnly: true example: '2018-04-15T00:00:00Z' scanners: description: Represents a list of scanners that have to run. type: array items: title: Scanner description: Represents a scanner within a scan. type: object properties: id: description: Unique identifier of a scanner. type: string format: uuid example: 7992f38a-df67-49d9-9f2f-98c63015a20c name: type: string description: The name of the scanner which searches for the appliance in the network. example: SMA_INVERTER_IGMP_HOST_DISCOVERY x-extensible-enum: - SMA_INVERTER_IGMP_HOST_DISCOVERY - SMA_INVERTER_ARP_HOST_DISCOVERY - SMA_METER - BCONTROL_METER - SOLAREDGE_INVERTER_METER_MODBUS_TCP - SOLAREDGE_INVERTER_METER_MODBUS_RTU - SOLARLOG_MONITOR - CUSTOMER_HOLFELDER_METER - CUSTOMER_HOLFELDER_INVERTER - E3DC_INVERTER_METER - KOSTAL_INVERTER - STUDER_INVERTER - FRONIUS_INVERTER - HUAWEI_INVERTER - KEBA_CHARGING_STATION - ECHARGE_CHARGING_STATION - INNOGY_CHARGING_STATION - ELECTRIS_METER - SOLARWATT_INVERTER_METER - ABL_CHARGING_STATION - SIEMENS_PAC_METER - JANITZA_METER - JANITZA_METER_RTU - EVTEC_CHARGING_STATION - HIKING_METER_RTU - EEBUS_FUEL_CELL_METER - KOSTAL_INVERTER_PLENTICORE - SONNENBATTERIE_UPNP - VIRTUAL_METER - MENNEKES_UPNP - ANYBUS_MBUS_CONVERTER_METER - EEBUS_GENERIC - SIMULATION_GENERIC - ALFEN_NG9XX_MODBUS_CHARGING_STATION - ALPITRONIC_HYPERCHARGER_MODBUS_CHARGING_STATION - MY_PV_AC_THOR_HEATER - COMPLEO_MODBUS_CHARGING_STATION - OCPP_CHARGING_STATION - BENDER_CHARGING_STATION - VOLTERION_REDOX_FLOW_BATTERY - XNET_METER - RSW_METER - SCHNEIDER_METER - INNOGY_MODBUS_CHARGING_STATION - MENNEKES_PREMIUM_MODBUS_CHARGING_STATION - PLPLANO_MODBUS_RTU_METER - HEIDELBERG_ENERGY_CONTROL_MODBUS_RTU_CHARGING_STATION - CARLO_GAVAZZI_MODBUS_RTU_METER - VESTEL_CHARGING_STATION - INNOTEC_HEAT_PUMP - WALLBE_MODBUS_CHARGING_STATION - EVBOX_MAX_CHARGING_STATION - ISKRAEMECO_METER - SUNGROW_MODBUS_INVERTER - WAGO_IO_DEVICE - GOE_CHARGING_STATION - XNET_CLOUD_HEAT_PUMP - XNET_CLOUD_GENERIC - LANDIS_GYR_METER - POWERDALE_CHARGING_STATION - EASTRON_SDM230_METER - EASTRON_SDM72DM_METER - ZUCCHETTI_CONNEXT_BOX - PLVARIO_ENERGY_METER_EM3 - ABB_OPC_UA_CHARGING_STATION - DATA_LOGGER_DEVICE - POWERSIDE_METER - PPC_METER - RUTENBECK_TCR_IP4_IO_DEVICE - JEAN_MUELLER_PL_MULTI_METER - ENPHASE_ENVOY_S_GATEWAY - SOLAX_MODBUS_RTU_INVERTER - ALPHA_ESS_HI10_HYBRID_INVERTER - ZUCCHETTI_MODBUS_RTU_INVERTER - STIEBEL_ELTRON_MODBUS_TCP_HEAT_PUMP - MENNEKES_AMTRON_COMPACT_2S_MODBUS_RTU_CHARGING_STATION - SAIA_PCD1_E_LINE_HEAT_PUMP - SUNGROW_SG_MODBUS_INVERTER - SOLAX_MODBUS_TCP_INVERTER - PHOENIX_CONTACT_EM_PRO_METER - DAIKIN_HOMEHUB_MODBUS_TCP_HEAT_PUMP - SOLPLANET_MODBUS_TCP_INVERTER - SUNGROW_SHXRS_SHXT_MODBUS_INVERTER - KOSTAD_DC_CHARGING_STATION - GIVENERGY_GIV_TCP_INVERTER - FOX_ESS_MODBUS_TCP_INVERTER - SHELLY_HTTP_METER - PIXII_MODBUS_TCP_BESS - GOODWE_MODBUS_TCP_INVERTER - READY_FOR_GRIDX - KOSTAL_ENECTOR_CHARGING_STATION - MENNEKES_4YOU_CHARGING_STATION - EKOENERGETYKA_CHARGING_STATION - VIESSMANN_EEBUS_INVERTER_AND_HEAT_PUMP - VAILLANT_EEBUS_HEAT_PUMP - PROLAN_EEBUS_STB - PPC_EEBUS_METER - THEBEN_SE_EEBUS_METER - DAIKIN_ALTHERMA4_MODBUS_TCP_HEAT_PUMP - FOXESS_CHARGING_STATION - BOSCH_BUDERUS_EEBUS_HEAT_PUMP - KOSTAL_EBOX_DC_B11_EEBUS_CHARGING_STATION - SOLPLANET_IBC_SOLAR_CHARGING_STATION - ADS_TEC_CHARGING_STATION - WOLF_EEBUS_HEAT_PUMP - SHELLY_3EMPRO_HTTP_METER - SHELLY_PRO2_HTTP_IO_DEVICE - SWISTEC_EEBUS_METER - BMW_DC_WALLBOX_EEBUS_CHARGING_STATION - SUNGROW_CHARGING_STATION - ETREL_INCH_DUO_CHARGING_STATION - ALPHAESS_SMILE_G3_T4_T10 - SUNGROW_EMS300CP_BESS - HUAWEI_SMART_LOGGER_BESS - SOLAX_MODBUS_TCP_METER x-readme-ref-name: ScannerName startedAt: description: The time at which the scan has started. type: string format: date-time readOnly: true example: '2018-04-15T00:00:00Z' finishedAt: description: The time at which the scan has finished. type: - string - 'null' format: date-time readOnly: true example: '2018-04-15T00:00:00Z' required: - id - name - startedAt - finishedAt x-readme-ref-name: Scanner appliances: description: Represents a list of appliances that have been detected during a scan. type: array items: title: Appliance description: 'Appliance represents a monitor-/controllable device such as Inverters, Meters and Heat Pumps. ' readOnly: true oneOf: - title: Inverter description: 'Inverter represents a monitor-/controllable inverter. It can be of kind: - `PV`/`PV_EXTERNAL`: used as photovoltaic only. - `BATTERY`: used as battery only. - `HYBRID`: used as both photovoltaic and battery. - `UNKNOWN`: default, when the inverter kind is not determined. ' allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: enum: - INVERTER type: string kind: description: 'Indicates the role of the inverter. Setting the kind impacts the system measurements. So it''s best to set it up correctly as early as possible in accordance to the actual installation in order for the measurement calculation to be correct (best during commissioning). ' type: string x-extensible-enum: - UNKNOWN - PV - PV_EXTERNAL - BATTERY - HYBRID x-readme-ref-name: InverterKind manufacturer: type: string example: SMA description: Manufacturer of the appliance. model: type: string example: Sunny Boy Storage 2.5 description: Model of the appliance. firmware: type: string example: 2.4.23.R description: Firmware version of the appliance. inverter: type: object description: The inverter specific information. properties: maxActivePowerOutput: description: Maximum active power output of the inverter in mW; set manually. Zero if not set. type: integer type: deprecated: true description: Describes the driver used to identify the inverter. This field is deprecated. type: string example: SUNGROW_SG_20_RT nominalPowerLimit: description: Designed maximal power output of the inverter in mW. type: integer hybridCalcMode: description: The calculation mode for inverters of HYBRID kind. type: integer x-extensible-enum: - 0 - 1 - 2 example: 0 battery: title: Battery Information type: object description: The battery specific information for inverters of BATTERY and HYBRID kind. properties: maxCharge: type: integer title: Battery's maximum charge in mW description: 'Maximum charge power in mW. This is a static hardware specification reported by the device at discovery time. ' format: int64 minimum: 0 maxDischarge: type: integer title: Battery's maximum discharge in mW description: 'Maximum discharge power in mW. This is a static hardware specification reported by the device at discovery time. ' format: int64 minimum: 0 controllable: type: boolean description: Controllable is true if the battery charging/discharging can be controlled. dischargeLimit: type: integer description: DischargeLimit is the minimum state of charge in % from 0-100 to discharge to. rechargeLimit: type: integer description: "RechargeLimit is the state of charge in % from 0-100 to which the battery needs to \nrecharge before allowing discharging again.\n" controlSettings: type: object description: Indicates the currently desired control settings for the battery. required: - value - command properties: value: type: integer description: Represents the charge/discharge power in mW. command: type: string description: Represents the current control command. enum: - none - charge - discharge x-readme-ref-name: AbstractBatteryInformation pv: title: PV Information type: object description: 'PV-specific configuration for inverters of kind ''PV'', ''PV_EXTERNAL'' and ''HYBRID''; for all other kinds, these fields are ignored. ' properties: arrays: type: array description: 'List of PV array configurations connected to the inverter. Each entry describes a distinct PV array with its own tilt, azimuth, and nominal power values. PATCHing the arrays field replaces the entire list of PV arrays. To update individual arrays, retrieve the current list, modify it as needed, and then PATCH the updated list back. Setting the arrays field to an empty list indicates that there are no PV arrays connected to the inverter. ' items: title: PV Array type: object description: 'Specification of a single PV array connected to the inverter. ' properties: nominalPower: type: integer format: int32 minimum: 0 description: Nominal power of the connected PV array in mW. tilt: type: integer format: int32 minimum: 0 maximum: 90 description: The inclination angle of the photovoltaic panels relative to the horizontal plane, measured in degrees (0° = flat horizontal, 90° = straight vertical). azimuth: type: integer format: int32 minimum: 0 maximum: 359 description: The compass orientation of the photovoltaic panels relative to true north, measured clockwise in degrees from 0 to 359 (0° = North, 90° = East, 180° = South, 270° = West). x-readme-ref-name: PVArray x-readme-ref-name: PVInformation x-readme-ref-name: AbstractInverter - required: - kind - inverter properties: hardwareStatus: title: Hardware Status type: object description: "HardwareStatus provides information about the condition of the inverter and in case of issues, \npossible follow-up actions the user/installer can perform to resolve them.\n" properties: state: type: string enum: - UNKNOWN - OK - WARNING - ERROR description: State of the inverter. action: type: string description: Recommended action to resolve ERROR/WARNING state. x-extensible-enum: - CONSULT_DEVICE_READOUT - CONTACT_INSTALLER - CONTACT_MANUFACTURER - CONTACT_GRID_OPERATOR errorCode: type: string description: Inverter manufacturer/model dependent error code formatted as it would be shown on display. description: type: string description: Contains details about the inverter ERROR and WARNING states. x-extensible-enum: - OTHER - GRID_FAULT - INSULATION_FAILURE - INTERFERENCE_DEVICE - FAN_FAULT - WAIT_FOR_UPDATE - SOFTWARE_FAULT - HARDWARE_FAULT - PARAMETER_FAULT - HIGH_TEMPERATURE - HIGH_DC_VOLTAGE - LOW_DC_POWER - DC_OVERCURRENT - INSTALLATION_FAULT - COMMUNICATION_FAULT - BATTERY_FAULT measuredAt: type: string format: date-time example: '2018-04-15T00:00:00Z' x-readme-ref-name: HardwareStatus inverter: required: - type battery: title: Battery Information type: object description: The battery specific information for inverters of BATTERY and HYBRID kind. allOf: - title: Battery Information type: object description: The battery specific information for inverters of BATTERY and HYBRID kind. properties: maxCharge: type: integer title: Battery's maximum charge in mW description: 'Maximum charge power in mW. This is a static hardware specification reported by the device at discovery time. ' format: int64 minimum: 0 maxDischarge: type: integer title: Battery's maximum discharge in mW description: 'Maximum discharge power in mW. This is a static hardware specification reported by the device at discovery time. ' format: int64 minimum: 0 controllable: type: boolean description: Controllable is true if the battery charging/discharging can be controlled. dischargeLimit: type: integer description: DischargeLimit is the minimum state of charge in % from 0-100 to discharge to. rechargeLimit: type: integer description: "RechargeLimit is the state of charge in % from 0-100 to which the battery needs to \nrecharge before allowing discharging again.\n" controlSettings: type: object description: Indicates the currently desired control settings for the battery. required: - value - command properties: value: type: integer description: Represents the charge/discharge power in mW. command: type: string description: Represents the current control command. enum: - none - charge - discharge x-readme-ref-name: AbstractBatteryInformation - required: - controllable x-readme-ref-name: BatteryInformation x-readme-ref-name: Inverter - title: Meter description: Meter represents a monitor-/controllable meter. allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - METER model: type: string example: B-control Energy Manager 300 description: Model of the meter. firmware: type: string example: '2.03' description: Firmware version of the meter. auxMeter: type: object description: The meter specific information. properties: location: type: string enum: - UNKNOWN - PV - GRID - BATTERY - HEAT_PUMP - FUEL_CELL - HEAT_PUMP_EXTERNAL - EVSTATION - PV_EXTERNAL - BTTP - HEATING - MISC - CLUSTER - WIND_TURBINE - AIR_CONDITIONER description: 'Indicates that the meter is in front of given location for measuring the consumption and production. ' type: deprecated: true description: Describes the driver used to identify the meter. This field is deprecated. type: string example: SE_SINGLE_PHASE modbusAddress: type: integer x-readme-ref-name: AbstractMeter - type: object required: - auxMeter - kind properties: kind: description: 'Indicates what the meter measures. Setting the kind impacts the system measurements. So it''s best to set it up correctly as early as possible in accordance to the actual installation in order for the measurement calculation to be correct (best during commissioning).' type: string enum: - UNKNOWN - PV - GRID - BATTERY - HEAT_PUMP - FUEL_CELL - HEAT_PUMP_EXTERNAL - EVSTATION - PV_EXTERNAL - BTTP - HEATING - MISC - CLUSTER - WIND_TURBINE - AIR_CONDITIONER x-readme-ref-name: MeterKind manufacturer: type: string example: TQ Systems description: Manufacturer of the meter. auxMeter: required: - location - type x-readme-ref-name: Meter - title: Heat Pump type: object description: Heat Pump represents a monitor-/controllable heat pump. allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - HEAT_PUMP manufacturer: type: string example: Stiebel Eltron description: Manufacturer of the heat pump. model: type: string example: WPMsystem description: Model of the heat pump. firmware: type: string example: mac_02:80:ad:24:d5:ab description: Firmware version of the heat pump. heatPump: title: Heat Pump Information type: object description: The heat pump specific information. properties: type: deprecated: true description: Describes the driver used to identify the heatpump. This field is deprecated. type: string x-extensible-enum: - UNKNOWN - EEBUS - SIMULATION - INNOTEC - XNET_CLOUD - EXT_IO_DEVICE - EXT_IO_DEVICE_DHW - STIEBEL_ELTRON_WPMSYSTEM - SAIA_PCD_E_LINE - DAIKIN_HOMEHUB - DAIKIN_ALTHERMA4 - BOSCH_BUDERUS controllable: type: boolean behindGCP: type: boolean description: 'Specifies whether this heat pump exists behind a GCP meter. ' withOwnTariff: description: '**Deprecated** Specifies whether this heat pump has its own meter and tariff. This field is no longer used and will be removed in a future version. ' deprecated: true type: boolean userControlEnabled: description: 'Specifies whether EMS control of this appliance is enabled by the user. ' type: boolean x-readme-ref-name: AbstractHeatPumpInformation x-readme-ref-name: AbstractHeatPump - required: - heatPump properties: heatPump: title: Heat Pump Information type: object description: The heat pump specific information. allOf: - title: Heat Pump Information type: object description: The heat pump specific information. properties: type: deprecated: true description: Describes the driver used to identify the heatpump. This field is deprecated. type: string x-extensible-enum: - UNKNOWN - EEBUS - SIMULATION - INNOTEC - XNET_CLOUD - EXT_IO_DEVICE - EXT_IO_DEVICE_DHW - STIEBEL_ELTRON_WPMSYSTEM - SAIA_PCD_E_LINE - DAIKIN_HOMEHUB - DAIKIN_ALTHERMA4 - BOSCH_BUDERUS controllable: type: boolean behindGCP: type: boolean description: 'Specifies whether this heat pump exists behind a GCP meter. ' withOwnTariff: description: '**Deprecated** Specifies whether this heat pump has its own meter and tariff. This field is no longer used and will be removed in a future version. ' deprecated: true type: boolean userControlEnabled: description: 'Specifies whether EMS control of this appliance is enabled by the user. ' type: boolean x-readme-ref-name: AbstractHeatPumpInformation - required: - type - controllable - behindGCP - userControlEnabled x-readme-ref-name: HeatPumpInformation x-readme-ref-name: HeatPump - title: EV Charging Station description: 'EV Charging Station represents a monitor-/controllable electric vehicle charging station. ' allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - EVSTATION kind: description: The kind of the ev charging station. type: string x-extensible-enum: - UNKNOWN - BATTERY_INTEGRATED manufacturer: type: string example: Echarge Hardy Barth description: Manufacturer of the ev charging station. model: type: string example: eCHARGE/PV description: Model of the ev charging station. firmware: type: string example: 0.38-78000001 description: Firmware version of the ev charging station. evseID: description: The EVSE-ID related to the charge point. type: string x-readme-ref-name: EVSEID evLoadManagementParameters: title: EvLoadManagementParameters description: 'Load management configuration for EV charging stations. **Deprecated** - Use the system''s EV charging station configuration instead. ' deprecated: true type: object properties: enabled: description: Indicates whether the load management is enabled. type: boolean maxPower: description: The maximum power in W. type: number format: double minimum: 0 x-readme-ref-name: EVLoadManagementParameters x-readme-ref-name: AbstractEVStation - required: - kind - evChargingStation properties: evChargingStation: title: EV Charging Station Information description: The ev charging specific information. type: object allOf: - title: EV Charging Station Information description: The EV Charging Station specific information. type: object properties: type: deprecated: true description: Describes the driver used to identify the ev charging station. This field is deprecated. type: string x-extensible-enum: - UNKNOWN - KE_CONTACT_P30 - E_CHARGE_ECB1 - INNOGY_LG2LAN - ABL - EVTEC - MENNEKES_AMTRON_EV_CHARGER_TYPE - EEBUS - SIMULATION - ALFEN_EV_NG9XX - ALPITRONIC_HYPERCHARGER - COMPLEO - OCPP - BENDER - INNOGY_MODBUS - MENNEKES_PREMIUM_MODBUS - HEIDELBERG_ENERGY_CONTROL - VESTEL - WALLBE_MODBUS - EVBOX_MAX - GOE - POWERDALE_ADVANCE - ZUCCHETTI - ABB_OPC_UA - MENNEKES_AMTRON_COMPACT_2S - KOSTAD_DC - MENNEKES_4YOU_560 - MENNEKES_4YOU_510 - KOSTAL_ENECTOR_AC_3_7_11_TYPE - R4GX_GENERIC - EKOENERGETYKA - FOXESS_L11PM - FOXESS_1KOMMA5_S_2_0 x-readme-ref-name: AbstractEVChargingStationInformation x-readme-ref-name: EVChargingStationInformation x-readme-ref-name: EVStation - title: IO Device description: IO devices represent configuration options that can be applied for appliances of the fieldbus coupler type allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - IO_DEVICE manufacturer: type: string example: Siemens AG description: Manufacturer of the io device. model: type: string example: Siemens AG 7KM2200-2EA30-1EA1 description: Model of the io device. firmware: type: string example: HW 3 SW V3.2.2 description: Firmware version of the io device. ioDevice: title: IO Device Information description: The io device specific information. type: object properties: type: deprecated: true description: Describes the driver used to identify the type of asset. This field is deprecated type: string x-extensible-enum: - UNKNOWN - WAGO - SGREADY - JANITZA_UMG604 - RUTENBECK_TCR_IP4 - SIEMENS_PAC_7KM_2200 - JANITZA - SHELLY - SHELLY3EMPRO - SHELLYPLUS1PM - SHELLYPLUS2PM - SHELLYPRO2 - SIMULATION inChannelsCount: type: integer description: The number of input ports on the device, real physical ports you can connect a cable to. outChannelsCount: type: integer description: The number of output ports on the device, real physical ports you can connect a cable to. x-readme-ref-name: AbstractIODeviceInformation x-readme-ref-name: AbstractIODevice - required: - ioDevice - properties: ioDevice: title: IO Device Information description: The io device specific information. type: object allOf: - title: IO Device Information description: The io device specific information. type: object properties: type: deprecated: true description: Describes the driver used to identify the type of asset. This field is deprecated type: string x-extensible-enum: - UNKNOWN - WAGO - SGREADY - JANITZA_UMG604 - RUTENBECK_TCR_IP4 - SIEMENS_PAC_7KM_2200 - JANITZA - SHELLY - SHELLY3EMPRO - SHELLYPLUS1PM - SHELLYPLUS2PM - SHELLYPRO2 - SIMULATION inChannelsCount: type: integer description: The number of input ports on the device, real physical ports you can connect a cable to. outChannelsCount: type: integer description: The number of output ports on the device, real physical ports you can connect a cable to. x-readme-ref-name: AbstractIODeviceInformation - properties: inputChannels: type: array description: Input channels of the fieldbus coupler, containing actions. items: title: IO Device Input Channel type: object properties: bitMask: type: string format: base64 description: BitMask used to identify the channel. bitValue: type: string format: base64 description: BitValue used to trigger the action. actions: type: array items: title: IO Device Input Action description: One individual input action, that can be registered to a channel of a fieldbus coppler appliance. type: object required: - name - value properties: name: type: string description: Name of the action. value: type: number description: Value of the action. Unit must be derived from Name. x-readme-ref-name: IODeviceInputAction x-readme-ref-name: IODeviceInputChannel outputChannels: type: array description: 'Output channels of the IODevice, containing actions. An output channel must not always use exactly one port, but can use multiple physical connections. SGReady heat pumps for example are connected using two output ports (which are grouped in one OutputChannel). ' items: title: IO Device Output Channel description: Represents one output channel of the IODevice. type: object properties: bitMask: type: string format: base64 description: Bit mask identifying the output channel. actions: type: array description: Actions (name/value pairs) that are applied to the channel when enabled. items: title: IO Device Output Action description: An individual output action, that can be registered to an output channel of an IODevice. type: object properties: bitValue: type: string format: base64 description: The value to write to the IODevice's output channel. Each action has its own bit value, to allow arbitrary combinations to be written to the output channel. sgReady: title: IO Device Output Action SGReady description: Used to specify a connection to a heat pump supporting the SGReady standard. type: object required: - pMin - pMax - state - applianceID properties: pMin: type: number pMax: type: number state: description: Represents one state of the sg ready standard. type: string enum: - UNKNOWN - 'OFF' - AUTO - RECOMMEND_ON - 'ON' applianceID: type: string format: uuid x-readme-ref-name: IODeviceOutputActionSGReady x-readme-ref-name: IODeviceOutputAction x-readme-ref-name: IODeviceOutputChannel required: - type - inChannelsCount - outChannelsCount x-readme-ref-name: IODeviceInformation x-readme-ref-name: IODevice - title: Heater type: object description: Heater represents a monitor-/controllable heater. allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - HEATER firmware: type: string example: '101.3' description: Firmware version of the heater. heater: description: The heater specific information. type: object properties: type: deprecated: true description: Describes the driver used to identify the heater. This field is deprecated type: string x-extensible-enum: - UNKNOWN - MY_PV_AC_THOR - SIMULATION - EXT_IO_DEVICE_ELECTRIC - MY_PV_AC_ELWA_2 medium: description: The medium the heater is working with. type: integer x-extensible-enum: - 0 - 1 - 2 - 3 - 4 nominalPower: description: The nominal power in mW of the heater. type: integer x-readme-ref-name: AbstractHeater - required: - heater properties: manufacturer: type: string example: my-PV description: Manufacturer of the heater. model: type: string example: AC•THOR description: Manufacturer of the heater. heater: required: - type - medium x-readme-ref-name: Heater - title: External controller description: Represent an external controller, used for DSO signaling and generally supervisory control. allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - EXTERNAL_CONTROLLER kind: description: The kind of the of the external controller. type: string x-extensible-enum: - UNKNOWN - VDE4110_GATEWAY manufacturer: type: string example: Loxone description: Manufacturer of the external controller. model: type: string example: Miniserver description: Model of the external controller. firmware: type: string description: Firmware of the external controller. externalController: description: The external controller specific information. type: object properties: type: deprecated: true description: Describes the driver used to identify the external controller. This field is deprecated. type: string x-extensible-enum: - UNKNOWN kind: deprecated: true description: Describes the specific kind of the external controller. type: string x-extensible-enum: - UNKNOWN - VDE4110_GATEWAY x-readme-ref-name: AbstractExternalController - required: - externalController - kind properties: externalController: required: - type - kind x-readme-ref-name: ExternalController - title: Electric Vehicle description: Electric Vehicle represents a monitor-/controllable electric vehicle. allOf: - title: Base Appliance description: 'BaseAppliance contains fields that all appliances have in common. Specific appliance types extend this schema and add new fields. ' type: object required: - id - inactive - createdAt - updatedAt - type - position - reverseFlow - connectionStatus - gatewayType - state - deviceID - systemID properties: id: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: Uniquely identifies the appliance. createdAt: type: string format: date-time description: Specifies when the appliance was created. updatedAt: type: string format: date-time description: Specifies when the appliance was updated the last time. connectionStatus: title: Appliance connection status type: object readOnly: true required: - status properties: status: type: string description: "Indicates the connection status of an appliance.\n \nThe connection status of an appliance is determined by the gateway. The gateway regularly\nsends the connection status of all connected appliances.\n\nIt is one of:\n- `AVAILABLE`: Appliance was reported as available by the gateway.\n- `UNAVAILABLE`: Appliance was reported as unavailable by the gateway.\n- `UNKNOWN`: The gateway didn't report a status for the appliance.\n\nIn case the connection status of the gateway this appliance belongs to is `TEMPORARILY_UNAVAILABLE` or `UNAVAILABLE`\nthe status is always `UNAVAILABLE`. \n" enum: - AVAILABLE - UNAVAILABLE - UNKNOWN contactedAt: type: string format: date-time deprecated: true description: "No longer supported. \n\nWill be set approximately to a value matching the status field.\nIf the appliance is `AVAILABLE`, it will be the current datetime.\nIf the appliance is `UNAVAILABLE`, it will be a datetime 24 hours in the past. \n" lastHeartbeatReceivedAt: type: string format: date-time description: 'When the last heartbeat of the gateway this appliance is connected was received. Deprecated: gateway heartbeats will be removed in future versions and this will be only estimated. ' deprecated: true x-readme-ref-name: ApplianceConnectionStatus gatewayType: type: string x-extensible-enum: - GRIDBOX - CLOUD description: 'Type of the gateway used to communicate with this asset: GRIDBOX → The asset is physically connected to a gridbox, through which it sends measurements and can be controlled. CLOUD → The asset is connected via a cloud-to-cloud integration, through which we receive measurements and can send commands. ' status: description: 'Status of the appliance. This field is set dynamically in the appliance handler. **Deprecated** - Use `ConnectionStatus` instead. ' type: string enum: - UNDEFINED - OK - WARNING - ERROR deprecated: true x-readme-ref-name: ApplianceStatus type: type: string example: INVERTER description: 'Describes the ''physical'' type of the appliance. See `kind` for further distinction of the type in terms of the appliance''s purpose/role, e.g. appliance with type=INVERTER and kind=BATTERY represents a battery inverter. ' x-readme-ref-name: ApplianceType inactive: type: boolean x-readme-ref-name: ApplianceInactive name: type: string description: Name of the appliance. x-readme-ref-name: ApplianceName reverseFlow: description: "**Supported ONLY for Meters.**\nFor all other asset types (e.g., EV Chargers, Inverters), this field is unused and **scheduled for removal**.\n\n**Usage (Meters only):**\nIf true, changes the energy flow's direction.\nIf during installation the input/output wiring is mixed up, set it to true in order to compensate for that.\nThis impact the consumption/production calculation as follows: \nIt switches the algebraic sign of the appliance's measurements, e.g. if an appliance measurement showed supply (+), it will change to feed-in (-) after this field is set to true (and vice versa).\n" type: boolean x-readme-ref-name: ApplianceReverseFlow room: type: string description: The physical room/location of the appliance in the building. x-readme-ref-name: ApplianceRoom serialnumber: type: string example: '1901000652' description: Serialnumber of the appliance. x-readme-ref-name: ApplianceSerialNumber network: title: Network description: Represents a network connection. type: object properties: interface: type: string example: eth0 description: Used network interface such as "eth0", "vpn0" etc. address: type: string example: 192.168.178.153 description: IP address of the device. port: type: integer format: int32 example: 0 description: Port used for the connection. protocol: type: string example: tcp/modbus description: Protocol used for the connection. x-readme-ref-name: Network parent: type: string format: uuid description: Specifies the parent appliance ID, for an appliance which is a child of a `INVERTER` of kind `HYBRID`. x-readme-ref-name: ApplianceParent loadSettings: title: Load Settings description: Configure load of appliance. type: object required: - disabled properties: disabled: type: boolean description: If true, disable electrical load of the appliance (e.g. stops charging for EV charging station). x-readme-ref-name: LoadSettings sensorSettings: title: Sensor Settings type: object allOf: - title: Sensor Settings description: '**DEPRECATED:** This is being phased out. It is historically only applicable to `METER` asset types and is deprecated/ignored for all other asset types. Settings specific to B-Control sensorbar appliances. Allows grouping sensors of one bar as different phases of a single appliance. ' type: object properties: sensorL1: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 1 of the appliance ' sensorL2: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 2 of the appliance ' sensorL3: type: integer description: '**DEPRECATED:** This property is only applicable to `METER` asset types. SensorID for phase 3 of the appliance ' x-readme-ref-name: AbstractSensorSettings - required: - createdAt - updatedAt properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time x-readme-ref-name: SensorSettings source: title: Source type: object required: - origin properties: origin: type: string description: "Specifies who created the appliance. This can be one of:\n- `GRIDBOX` if the appliance was found during a scan using a gridBox.\n- `API` if a user of the gridX API used the 'Create Appliance' endpoint\n to create this appliance.\n- `UNKNOWN` otherwise.\n" enum: - UNKNOWN - GRIDBOX - API example: API uri: type: string deprecated: true description: 'Contains an URI identifying the exact resource that created this appliance. If origin is ''GRIDBOX'' the value will point to the gateway object of the gridBox. If origin is ''API'' the value will be empty. The ''UNKNOWN'' origin should not occur in practice and is reserved for special cases (for now). ' example: gateways/b30510fa-a8a5-475f-a75d-82a46cb62582 x-readme-ref-name: Source commissioningKind: title: Commissioning Kind description: 'Indicates special requirements to be fulfilled during the commissioning for this appliance. If empty or unset (default), the appliance can be commissioned as regular. - `property:CryptoSettings` means that the appliance property `CryptoSettings` needs to be set, e.g. for authenticating towards it with an appliance-specific API token. - `flow:Pairing` means that a coupling or pairing flow has to be initiated and run-through in order for the appliance to behave correctly. ' type: string enum: - property:CryptoSettings - flow:Pairing x-readme-ref-name: CommissioningKind state: title: State description: Contains information about the appliance's state. type: object allOf: - title: State description: Contains information about the appliance's state. type: object properties: current: description: The state the appliance is currently in. example: SCANNED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState transitions: description: "List with all the possible state transitions an appliance can go through. \nAn appliance can go from a `starting` state to a `target` state.\n" type: array items: title: State Transition description: Defines the properties of a transition an appliance can go through. type: object required: - start - target properties: start: description: The starting state of the appliance. example: CONNECTING title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState target: description: The target state of the appliance. example: DISCONNECTED title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: ApplianceState x-readme-ref-name: StateTransition x-readme-ref-name: AbstractState - required: - current - desired properties: desired: description: The desired state of the appliance. example: CONNECTED x-readme-ref-name: DesiredState title: Appliance State type: string enum: - UNKNOWN_APPLIANCE_STATE - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: State energySettings: title: Energy Management Settings description: Contains energy management information type: object allOf: - title: Energy Management Settings description: Contains energy management information type: object properties: minControlInterval: type: integer deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. Minimum interval in milliseconds in which this appliance can receive control commands, e.g. new power setpoint. ' socMax: deprecated: true description: '**DEPRECATED.** This field will be removed in a future version. The maximum state of charge an energy storage can be charged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMax: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold above which no charging is allowed once SoC max is reached, in a range from [0-100] in %. Must be smaller than or equal to socMax. ' type: number format: double minimum: 0 maximum: 100 socMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The minimum state of charge an energy storage can be discharged to in a range from [0-100] in %. ' type: number format: double minimum: 0 maximum: 100 socLockMin: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The threshold below which no discharging is allowed once SoC min is reached, in a range from [0-100] in %. Must be larger than or equal to socMin. ' type: number format: double minimum: 0 maximum: 100 socDeepDischarge: deprecated: true description: '**DEPRECATED.** Legacy artifact. This field is non-functional and scheduled for removal. The lowest state of charge an energy storage can reach, in a range from [0-100] in %. Below this it is not usable and a forced recharge to at least socMin is required. ' type: number format: double minimum: 0 maximum: 100 phaseMapping: description: "Contains three indices representing the actual phases on the grid connection point this appliance is connected to. \nNote that the first phase has index 0 and last phase index 2.\nThe index of the sequence is the phase on the gcp and the values are the appliance phases. Unused phases are marked with -1.\n" type: - array - 'null' minItems: 3 maxItems: 3 items: type: integer temperatureExtremeMax: description: 'The temperature to which the system should be heated up to in °C, if there is an energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureExtremeMin: description: 'The minimum temperature the system can reach in °C. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMax: description: 'The temperature to which the system should be heated up to in °C, if there is no energy surplus. *Deprecated for non-heater assets: This property is only applicable to Heaters. Setting this value for any other asset type has absolutely no effect and it will be explicitly removed from the schema for all non-heater assets in the future.* ' type: number format: double temperatureComfortMin: deprecated: true description: "**DEPRECATED.** This legacy field is non-functional and is scheduled for removal. \nThe EMS now uses a single value provided in `temperatureComfortMax` as its primary setpoint for optimization, rather than a range.\n\nThe temperature at which the system starts to heat up to in °C.\n" type: number format: double surplusThreshold: type: integer description: 'For other asset types, this field is unused and scheduled for removal. The supply surplus threshold for the EMS to activate the appliance (in Watt). ' x-readme-ref-name: AbstractEnergyManagementSettings - required: - updatedAt properties: updatedAt: description: Specifies when the energy management settings were updated the last time. type: string format: date-time x-readme-ref-name: EnergyManagementSettings cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object allOf: - type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting - properties: createdAt: type: string format: date-time description: Specifies when the crypto key was created. updatedAt: type: string format: date-time description: Specifies when the crypto key was updated the last time. x-readme-ref-name: CryptoSetting protocol: title: Protocol description: Network protocol supported by the appliance type: string example: EEBUS enum: - UNKNOWN - EEBUS - MODBUS_TCP - MODBUS_RTU - HTTP_REST - OCPP x-readme-ref-name: ApplianceProtocol systemID: type: string format: uuid example: ec4d0c89-a604-49ac-82f0-427f9cb42204 description: ID of the system this appliances belongs to. systemName: type: string description: Name of the system this appliances belongs to. installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: BaseAppliance - type: object properties: type: type: string enum: - EV manufacturer: type: string example: Hyundai description: Manufacturer of the electric vehicle. model: type: string example: Ioniq 5 description: Model of the electric vehicle. electricVehicle: description: The electric vehicle specific information. type: object properties: kind: type: string description: Describes the specific kind of the electric vehicle. x-extensible-enum: - EV year: type: integer description: Describes the year the electric vehicle was produced. example: 2022 x-readme-ref-name: AbstractEV - required: - model - manufacturer - electricVehicle properties: electricVehicle: required: - kind x-readme-ref-name: EV discriminator: propertyName: type mapping: INVERTER: '#/components/schemas/Inverter' METER: '#/components/schemas/Meter' HEAT_PUMP: '#/components/schemas/HeatPump' EVSTATION: '#/components/schemas/EVStation' IO_DEVICE: '#/components/schemas/IODevice' HEATER: '#/components/schemas/Heater' EXTERNAL_CONTROLLER: '#/components/schemas/ExternalController' EV: '#/components/schemas/EV' x-readme-ref-name: Appliance required: - id x-readme-ref-name: Scan '400': description: Malformed request. content: application/vnd.gridx.v2+json: schema: readOnly: true allOf: - title: General Exception description: Represents a general error structure returned by our REST API. type: object properties: message: type: string description: Message represents the message reported to the user. details: type: array description: 'Details represents detail information for the user to fix this problem ' items: type: string required: - message x-readme-ref-name: GeneralException - title: ClientError - Bad Request description: 'Bad Request indicates that the request body is not a valid JSON or it contains a invalid json type. ' example: message: Problems parsing JSON x-readme-ref-name: BadRequestException '403': description: Forbidden. content: application/vnd.gridx.v2+json: schema: readOnly: true allOf: - title: General Exception description: Represents a general error structure returned by our REST API. type: object properties: message: type: string description: Message represents the message reported to the user. details: type: array description: 'Details represents detail information for the user to fix this problem ' items: type: string required: - message x-readme-ref-name: GeneralException - title: UnauthorizedError - Forbidden Error description: Forbidden Error example: message: Bad credentials x-readme-ref-name: ForbiddenException '500': description: There has been an internal error on our side. We're looking into it. content: application/vnd.gridx.v2+json: schema: readOnly: true allOf: - title: General Exception description: Represents a general error structure returned by our REST API. type: object properties: message: type: string description: Message represents the message reported to the user. details: type: array description: 'Details represents detail information for the user to fix this problem ' items: type: string required: - message x-readme-ref-name: GeneralException - title: ServerSideError - Internal Server Error description: Internal Server Error example: message: Internal Server Error x-readme-ref-name: InternalException security: - HeaderAuth: - ScansRead x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/scans" headers = {"accept": "application/vnd.gridx.v2+json"} response = requests.get(url, headers=headers) print(response.text)' - lang: shell label: Shell source: "curl --request GET \\\n --url https://api.gridx.de/gateways/gatewayID/scans \\\n --header 'accept: application/vnd.gridx.v2+json'" - lang: go label: Go source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io\"\n)\n\nfunc main() {\n\n\turl := \"https://api.gridx.de/gateways/gatewayID/scans\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"accept\", \"application/vnd.gridx.v2+json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\n\tfmt.Println(string(body))\n\n}" - lang: javascript label: Javascript source: "const options = {method: 'GET', headers: {accept: 'application/vnd.gridx.v2+json'}};\n\nfetch('https://api.gridx.de/gateways/gatewayID/scans', options)\n .then(res => res.json())\n .then(res => console.log(res))\n .catch(err => console.error(err));" - lang: java label: Java source: "OkHttpClient client = new OkHttpClient();\n\nRequest request = new Request.Builder()\n .url(\"https://api.gridx.de/gateways/gatewayID/scans\")\n .get()\n .addHeader(\"accept\", \"application/vnd.gridx.v2+json\")\n .build();\n\nResponse response = client.newCall(request).execute();" - lang: java label: Kotlin source: "val client = OkHttpClient()\n\nval request = Request.Builder()\n .url(\"https://api.gridx.de/gateways/gatewayID/scans\")\n .get()\n .addHeader(\"accept\", \"application/vnd.gridx.v2+json\")\n .build()\n\nval response = client.newCall(request).execute()" - lang: javascript label: Swift source: 'import Foundation let url = URL(string: "https://api.gridx.de/gateways/gatewayID/scans")! var request = URLRequest(url: url) request.httpMethod = "GET" request.timeoutInterval = 10 request.allHTTPHeaderFields = ["accept": "application/vnd.gridx.v2+json"] let (data, _) = try await URLSession.shared.data(for: request) print(String(decoding: data, as: UTF8.self))' - lang: csharp label: C# source: 'using RestSharp; var options = new RestClientOptions("https://api.gridx.de/gateways/gatewayID/scans"); var client = new RestClient(options); var request = new RestRequest(""); request.AddHeader("accept", "application/vnd.gridx.v2+json"); var response = await client.GetAsync(request); Console.WriteLine("{0}", response.Content); ' servers: - url: https://api.gridx.de description: Production components: securitySchemes: HeaderAuth: type: apiKey name: Authorization in: header description: Enter either the JWT token with the prefix `Bearer ` or an API token with the prefix `Token ` x-refined-from: - gridx-api.json - gridx-ai-openapi.yml