openapi: 3.2.0 info: title: Gridx Ai Appliance 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 Appliance 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: Appliance x-displayName: Appliance paths: /gateways/{gatewayID}/appliances/{applianceID}/measurements/appliance: get: operationId: getSystemRawMeasurements summary: List Appliance's Raw Measurements description: 'Lists raw measurements of an appliance over a period of time. The provided `interval` must not span more than 24 hours. The resolution cannot be controlled. The granularity at which we store measurements varies from appliance to appliance, firmware and configuration. To retrieve raw measurements of hybrid inverters, use the appliance IDs of the children (battery or PV) appliances. Listing raw measurements is only supported for appliances of type: * `INVERTER` * `METER` * `EVSTATION` * `HEAT_PUMP`' tags: - Appliance security: - HeaderAuth: - ApplianceMeasurementsRead 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: applianceID description: 'Unique identifier used to access an appliance. ' in: path required: true schema: type: string format: uuid example: bb2681ab-9526-49ca-bc52-a5f4ec366958 - 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 responses: '200': description: Returned raw measurement. content: application/vnd.gridx.v2+json: schema: description: List of raw measurements of an appliance. type: array items: description: Raw measurement of an appliance. type: object oneOf: - title: Inverter's Measurements type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured. gridFrequency: type: integer format: int32 description: The locally measured grid frequency in centi (10^-2) Hz. acCurrent: type: integer format: int32 description: AC current in mA. l1ACCurrent: type: integer format: int32 description: AC current on phase L1 in mA. l2ACCurrent: type: integer format: int32 description: AC current on phase L2 in mA. l3ACCurrent: type: integer format: int32 description: AC current on phase L3 in mA. l1ACVoltage: type: integer format: int32 description: AC voltage on phase L1 in mV. l2ACVoltage: type: integer format: int32 description: AC voltage on phase L2 in mV. l3ACVoltage: type: integer format: int32 description: AC voltage on phase L3 mV. acActivePower: type: integer format: int32 description: AC active power in mW. acReactivePower: type: integer format: int32 description: AC reactive power in VAr. acApparentPower: type: integer format: int32 description: AC apparent power VA. dcCurrent: type: integer format: int32 description: DC current in mA. dcVoltage: type: integer format: int32 description: DC voltage in mV. dcPower: type: integer format: int32 description: DC power in mW. battery: title: A measurement produced by a battery (inverter). type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured in UTC using RFC3339 format. capacity: type: integer format: int32 minimum: 0 description: Capacity in Wh. nominalCapacity: type: integer format: int32 minimum: 0 description: Nominal capacity in Wh. stateOfCharge: type: integer format: int32 minimum: 0 description: Value in range 0-100, state of charge in percent. stateOfHealth: type: integer format: int32 minimum: 0 description: Value in range 0-100, health of the battery in percent. temperature: type: integer format: int32 description: Temperature of the battery in degrees Celsius. presentCharge: type: integer format: int32 minimum: 0 description: Current charge of the battery in mW. presentDischarge: type: integer format: int32 minimum: 0 description: Current discharge of the battery in mW. x-readme-ref-name: BatteryMeasurementRaw required: - measuredAt x-readme-ref-name: InverterMeasurement - title: Meter's Measurement type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured. l1ActivePower: type: integer format: int64 description: L1 Active Power in mW. l1ActivePowerReadingPositive: type: integer format: int64 description: L1 Active Power Reading (Imported Energy) in Ws. l1ActivePowerReadingNegative: type: integer format: int64 description: L2 Active Power Reading (Exported Energy) in Ws. l1ReactivePower: type: integer format: int64 description: L1 Reactive Power in VAr. l1ReactivePowerReadingPositive: type: integer format: int64 description: L1 Reactive Power Reading (Imported Energy) in VArs. l1ReactivePowerReadingNegative: type: integer format: int64 description: L1 Reactive Power Reading (Exported Energy) in VArs. l1ApparentPower: type: integer format: int64 description: L1 Apparent Power in VA. l1ApparentPowerReadingPositive: type: integer format: int64 description: L1 Apparent Power Reading (Imported Energy) in VAs. l1ApparentPowerReadingNegative: type: integer format: int64 description: L1 Apparent Power Reading (Exported Energy) in VAs. l1Current: type: integer format: int32 description: L1 Current in mA. l1Voltage: type: integer format: int32 description: L1 Voltage in mV. l1ImportPowerLimit: type: integer format: int64 description: L1 maximum imported power in mW. l2ActivePower: type: integer format: int64 description: L2 Active Power in mW. l2ActivePowerReadingPositive: type: integer format: int64 description: L2 Active Power Reading (Imported Energy) in Ws. l2ActivePowerReadingNegative: type: integer format: int64 description: L2 Active Power Reading (Exported Energy) in Ws. l2ReactivePower: type: integer format: int64 description: L2 Reactive Power in VAr. l2ReactivePowerReadingPositive: type: integer format: int64 description: L2 Reactive Power Reading (Imported Energy) in VArs. l2ReactivePowerReadingNegative: type: integer format: int64 description: L2 Reactive Power Reading (Exported Energy) in VArs. l2ApparentPower: type: integer format: int64 description: L2 Apparent Power in VA. l2ApparentPowerReadingPositive: type: integer format: int64 description: L2 Apparent Power Reading (Imported Energy) in VAs. l2ApparentPowerReadingNegative: type: integer format: int64 description: L2 Apparent Power Reading (Exported Energy) in VAs. l2Current: type: integer format: int32 description: L2 Current in mA. l2Voltage: type: integer format: int32 description: L2 Voltage in mV. l2ImportPowerLimit: type: integer format: int64 description: L2 maximum imported power in mW. l3ActivePower: type: integer format: int64 description: L3 Active Power in mW. l3ActivePowerReadingPositive: type: integer format: int64 description: L3 Active Power Reading (Imported Energy) in Ws. l3ActivePowerReadingNegative: type: integer format: int64 description: L3 Active Power Reading (Exported Energy) in Ws. l3ReactivePower: type: integer format: int64 description: L3 Reactive Power in VAr. l3ReactivePowerReadingPositive: type: integer format: int64 description: L3 Reactive Power Reading (Imported Energy) in VArs. l3ReactivePowerReadingNegative: type: integer format: int64 description: L3 Reactive Power Reading (Exported Energy) in VArs. l3ApparentPower: type: integer format: int64 description: L3 Apparent Power in VA. l3ApparentPowerReadingPositive: type: integer format: int64 description: L3 Apparent Power Reading (Imported Energy) in VAs. l3ApparentPowerReadingNegative: type: integer format: int64 description: L3 Apparent Power Reading (Exported Energy) in VAs. l3Current: type: integer format: int32 description: L3 Current in mA. l3Voltage: type: integer format: int32 description: L3 Voltage in mV. l3ImportPowerLimit: type: integer format: int64 description: L3 maximum imported power in mW. sumActivePower: type: integer format: int64 description: Sum Active Power in mW. sumActivePowerReadingPositive: type: integer format: int64 description: Sum Active Power Reading (Imported Energy) in Ws. sumActivePowerReadingNegative: type: integer format: int64 description: Sum Active Power Reading (Exported Energy) in Ws. sumApparentPower: type: integer format: int64 description: Sum Apparent Power in VA. sumApparentPowerReadingPositive: type: integer format: int64 description: Sum Apparent Power Reading (Imported Energy) in VAs. sumApparentPowerReadingNegative: type: integer format: int64 description: Sum Apparent Power Reading (Exported Energy) in VAs. sumReactivePower: type: integer format: int64 description: Sum Reactive Power in VA. sumReactivePowerReadingPositive: type: integer format: int64 description: Sum Reactive Power Reading (Imported Energy) in VAs. sumReactivePowerReadingNegative: type: integer format: int64 description: Sum Reactive Power Reading (Exported Energy) in VAs. sumImportPowerLimit: type: integer format: int64 description: Sum Maximum imported power in mW. sumPowerFactor: type: integer format: int32 description: Power factor in deg. x-readme-ref-name: AUXMeterMeasurement - title: EV Charging Station's Measurement type: object properties: measuredAt: type: string format: date-time description: Date and time the data point was collected. l1Voltage: type: integer format: int32 description: Voltage for first phase in mW. l2Voltage: type: integer format: int32 description: Voltage for second phase in mW. l3Voltage: type: integer format: int32 description: Voltage for third phase in mW. l1Current: type: integer format: int32 description: Current for first phase in mA. l2Current: type: integer format: int32 description: Current for second phase in mA. l3Current: type: integer format: int32 description: Current for third phase in mA. realPower: type: integer format: int64 description: 'Real Power in mW. Positive values mean charging, negative values mean discharging (V2G; currently not done). ' powerFactor: type: integer format: int32 description: Power Factor in 0.1% (cosphi). l1RealPower: type: integer format: int64 description: Real Power L1 in mW. l2RealPower: type: integer format: int64 description: Real Power L2 in mW. l3RealPower: type: integer format: int64 description: Real Power L3 in mW. temperature: type: integer format: int64 description: Temperature inside the charging station in °C. capacity: type: integer format: int32 description: The total capacity of the EV battery in Wh. stateOfCharge: type: number format: double description: 'The current state of charge of the EV battery in percent from 0.0 - 100.0%. ' maxCharge: type: integer format: int32 description: Maximum allowed charge power in mW. minCharge: type: integer format: int32 description: 'Minimum allowed charge power in mW, below this power the EV won''t charge. ' maxDischarge: type: integer format: int32 description: Maximum allowed discharge power in mW. stationState: type: string description: 'State indicating whether the charging station is charging, ready, in error state, etc. ' plugState: type: string description: 'State indicates whether an EV is plugged into the charging station. ' pluggedIn: type: boolean description: 'PluggedIn true if an electric vehicle is currently plugged into the charging station. ' tokenID: type: string description: 'TokenID is the used authentication token at the charging station. ' x-readme-ref-name: EVChargingStationMeasurement - title: A measurement produced by a heatpump appliance. type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured in UTC using RFC3339 format. power: type: integer description: Power of the heatpump in mW. powerL1: type: integer description: Power for the first phase in mW . powerL2: type: integer powerL3: type: integer minPower: type: integer maxPower: type: integer readyState: type: string default: UNKNOWN enum: - UNKNOWN - 'OFF' - AUTO - RECOMMEND_ON - 'ON' averageTemperature: type: number format: double controlledTemperature: type: number format: double baseLineTemperature: type: number format: double heatSourceTemperature: type: number format: double outdoorTemperature: type: number format: double operationStatus: type: string default: UNKNOWN enum: - UNKNOWN - HEATING - DRINKING_HOT_WATER - POOL_HEATING - EVU_LOCK - DEFROST - 'OFF' - EXTERNAL_SOURCE - COOLING energyHeating: type: number format: double energyDrinkingHotWater: type: number format: double required: - operationStatus x-readme-ref-name: HeatPumpMeasurementRaw x-readme-ref-name: ApplianceMeasurement x-readme-ref-name: ApplianceMeasurements '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 '404': description: Entity Not found. 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '422': description: Validation failed. 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 - Validation description: 'Validation indicates that the request body contains fields which does not pass the validation. ' type: object required: - message - details example: message: Validation failed details: - email is not valid x-readme-ref-name: InvalidException '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 x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/appliances/applianceID/measurements/appliance" 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/appliances/applianceID/measurements/appliance \\\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/appliances/applianceID/measurements/appliance\"\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/appliances/applianceID/measurements/appliance', 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/appliances/applianceID/measurements/appliance\")\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/appliances/applianceID/measurements/appliance\")\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/appliances/applianceID/measurements/appliance")! 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/appliances/applianceID/measurements/appliance"); 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 /gateways/{gatewayID}/appliances/{applianceID}/measurements: get: operationId: getSystemCombinedMeasurements summary: List Appliance's Combined Measurements description: 'Lists combinations of appliance measurements and energy management measurements. This endpoints adds a "convenience" method for fetching raw measurements and energy management measurements together, by combining them into a single measurement object. It is usually used to inspect the EMS behavior in correspondence to raw values reported by the appliance. The requested `interval` must not span more than 24 hours. To retrieve raw measurements of hybrid inverters, use the appliance IDs of the children (battery or PV) appliances. Listing combined measurements is only supported for appliances of type: * `INVERTER` * `METER` * `EVSTATION` * `HEAT_PUMP`' tags: - Appliance security: - HeaderAuth: - ApplianceMeasurementsRead 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: applianceID description: 'Unique identifier used to access an appliance. ' in: path required: true schema: type: string format: uuid example: bb2681ab-9526-49ca-bc52-a5f4ec366958 - 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 responses: '200': description: Combined measurements have been returned successfully. content: application/vnd.gridx.v2+json: schema: type: array items: type: object description: Combined appliance and energy management measurement. allOf: - oneOf: - title: Inverter's Measurements type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured. gridFrequency: type: integer format: int32 description: The locally measured grid frequency in centi (10^-2) Hz. acCurrent: type: integer format: int32 description: AC current in mA. l1ACCurrent: type: integer format: int32 description: AC current on phase L1 in mA. l2ACCurrent: type: integer format: int32 description: AC current on phase L2 in mA. l3ACCurrent: type: integer format: int32 description: AC current on phase L3 in mA. l1ACVoltage: type: integer format: int32 description: AC voltage on phase L1 in mV. l2ACVoltage: type: integer format: int32 description: AC voltage on phase L2 in mV. l3ACVoltage: type: integer format: int32 description: AC voltage on phase L3 mV. acActivePower: type: integer format: int32 description: AC active power in mW. acReactivePower: type: integer format: int32 description: AC reactive power in VAr. acApparentPower: type: integer format: int32 description: AC apparent power VA. dcCurrent: type: integer format: int32 description: DC current in mA. dcVoltage: type: integer format: int32 description: DC voltage in mV. dcPower: type: integer format: int32 description: DC power in mW. battery: title: A measurement produced by a battery (inverter). type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured in UTC using RFC3339 format. capacity: type: integer format: int32 minimum: 0 description: Capacity in Wh. nominalCapacity: type: integer format: int32 minimum: 0 description: Nominal capacity in Wh. stateOfCharge: type: integer format: int32 minimum: 0 description: Value in range 0-100, state of charge in percent. stateOfHealth: type: integer format: int32 minimum: 0 description: Value in range 0-100, health of the battery in percent. temperature: type: integer format: int32 description: Temperature of the battery in degrees Celsius. presentCharge: type: integer format: int32 minimum: 0 description: Current charge of the battery in mW. presentDischarge: type: integer format: int32 minimum: 0 description: Current discharge of the battery in mW. x-readme-ref-name: BatteryMeasurementRaw required: - measuredAt x-readme-ref-name: InverterMeasurement - title: Meter's Measurement type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured. l1ActivePower: type: integer format: int64 description: L1 Active Power in mW. l1ActivePowerReadingPositive: type: integer format: int64 description: L1 Active Power Reading (Imported Energy) in Ws. l1ActivePowerReadingNegative: type: integer format: int64 description: L2 Active Power Reading (Exported Energy) in Ws. l1ReactivePower: type: integer format: int64 description: L1 Reactive Power in VAr. l1ReactivePowerReadingPositive: type: integer format: int64 description: L1 Reactive Power Reading (Imported Energy) in VArs. l1ReactivePowerReadingNegative: type: integer format: int64 description: L1 Reactive Power Reading (Exported Energy) in VArs. l1ApparentPower: type: integer format: int64 description: L1 Apparent Power in VA. l1ApparentPowerReadingPositive: type: integer format: int64 description: L1 Apparent Power Reading (Imported Energy) in VAs. l1ApparentPowerReadingNegative: type: integer format: int64 description: L1 Apparent Power Reading (Exported Energy) in VAs. l1Current: type: integer format: int32 description: L1 Current in mA. l1Voltage: type: integer format: int32 description: L1 Voltage in mV. l1ImportPowerLimit: type: integer format: int64 description: L1 maximum imported power in mW. l2ActivePower: type: integer format: int64 description: L2 Active Power in mW. l2ActivePowerReadingPositive: type: integer format: int64 description: L2 Active Power Reading (Imported Energy) in Ws. l2ActivePowerReadingNegative: type: integer format: int64 description: L2 Active Power Reading (Exported Energy) in Ws. l2ReactivePower: type: integer format: int64 description: L2 Reactive Power in VAr. l2ReactivePowerReadingPositive: type: integer format: int64 description: L2 Reactive Power Reading (Imported Energy) in VArs. l2ReactivePowerReadingNegative: type: integer format: int64 description: L2 Reactive Power Reading (Exported Energy) in VArs. l2ApparentPower: type: integer format: int64 description: L2 Apparent Power in VA. l2ApparentPowerReadingPositive: type: integer format: int64 description: L2 Apparent Power Reading (Imported Energy) in VAs. l2ApparentPowerReadingNegative: type: integer format: int64 description: L2 Apparent Power Reading (Exported Energy) in VAs. l2Current: type: integer format: int32 description: L2 Current in mA. l2Voltage: type: integer format: int32 description: L2 Voltage in mV. l2ImportPowerLimit: type: integer format: int64 description: L2 maximum imported power in mW. l3ActivePower: type: integer format: int64 description: L3 Active Power in mW. l3ActivePowerReadingPositive: type: integer format: int64 description: L3 Active Power Reading (Imported Energy) in Ws. l3ActivePowerReadingNegative: type: integer format: int64 description: L3 Active Power Reading (Exported Energy) in Ws. l3ReactivePower: type: integer format: int64 description: L3 Reactive Power in VAr. l3ReactivePowerReadingPositive: type: integer format: int64 description: L3 Reactive Power Reading (Imported Energy) in VArs. l3ReactivePowerReadingNegative: type: integer format: int64 description: L3 Reactive Power Reading (Exported Energy) in VArs. l3ApparentPower: type: integer format: int64 description: L3 Apparent Power in VA. l3ApparentPowerReadingPositive: type: integer format: int64 description: L3 Apparent Power Reading (Imported Energy) in VAs. l3ApparentPowerReadingNegative: type: integer format: int64 description: L3 Apparent Power Reading (Exported Energy) in VAs. l3Current: type: integer format: int32 description: L3 Current in mA. l3Voltage: type: integer format: int32 description: L3 Voltage in mV. l3ImportPowerLimit: type: integer format: int64 description: L3 maximum imported power in mW. sumActivePower: type: integer format: int64 description: Sum Active Power in mW. sumActivePowerReadingPositive: type: integer format: int64 description: Sum Active Power Reading (Imported Energy) in Ws. sumActivePowerReadingNegative: type: integer format: int64 description: Sum Active Power Reading (Exported Energy) in Ws. sumApparentPower: type: integer format: int64 description: Sum Apparent Power in VA. sumApparentPowerReadingPositive: type: integer format: int64 description: Sum Apparent Power Reading (Imported Energy) in VAs. sumApparentPowerReadingNegative: type: integer format: int64 description: Sum Apparent Power Reading (Exported Energy) in VAs. sumReactivePower: type: integer format: int64 description: Sum Reactive Power in VA. sumReactivePowerReadingPositive: type: integer format: int64 description: Sum Reactive Power Reading (Imported Energy) in VAs. sumReactivePowerReadingNegative: type: integer format: int64 description: Sum Reactive Power Reading (Exported Energy) in VAs. sumImportPowerLimit: type: integer format: int64 description: Sum Maximum imported power in mW. sumPowerFactor: type: integer format: int32 description: Power factor in deg. x-readme-ref-name: AUXMeterMeasurement - title: EV Charging Station's Measurement type: object properties: measuredAt: type: string format: date-time description: Date and time the data point was collected. l1Voltage: type: integer format: int32 description: Voltage for first phase in mW. l2Voltage: type: integer format: int32 description: Voltage for second phase in mW. l3Voltage: type: integer format: int32 description: Voltage for third phase in mW. l1Current: type: integer format: int32 description: Current for first phase in mA. l2Current: type: integer format: int32 description: Current for second phase in mA. l3Current: type: integer format: int32 description: Current for third phase in mA. realPower: type: integer format: int64 description: 'Real Power in mW. Positive values mean charging, negative values mean discharging (V2G; currently not done). ' powerFactor: type: integer format: int32 description: Power Factor in 0.1% (cosphi). l1RealPower: type: integer format: int64 description: Real Power L1 in mW. l2RealPower: type: integer format: int64 description: Real Power L2 in mW. l3RealPower: type: integer format: int64 description: Real Power L3 in mW. temperature: type: integer format: int64 description: Temperature inside the charging station in °C. capacity: type: integer format: int32 description: The total capacity of the EV battery in Wh. stateOfCharge: type: number format: double description: 'The current state of charge of the EV battery in percent from 0.0 - 100.0%. ' maxCharge: type: integer format: int32 description: Maximum allowed charge power in mW. minCharge: type: integer format: int32 description: 'Minimum allowed charge power in mW, below this power the EV won''t charge. ' maxDischarge: type: integer format: int32 description: Maximum allowed discharge power in mW. stationState: type: string description: 'State indicating whether the charging station is charging, ready, in error state, etc. ' plugState: type: string description: 'State indicates whether an EV is plugged into the charging station. ' pluggedIn: type: boolean description: 'PluggedIn true if an electric vehicle is currently plugged into the charging station. ' tokenID: type: string description: 'TokenID is the used authentication token at the charging station. ' x-readme-ref-name: EVChargingStationMeasurement - title: A measurement produced by a heatpump appliance. type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured in UTC using RFC3339 format. power: type: integer description: Power of the heatpump in mW. powerL1: type: integer description: Power for the first phase in mW . powerL2: type: integer powerL3: type: integer minPower: type: integer maxPower: type: integer readyState: type: string default: UNKNOWN enum: - UNKNOWN - 'OFF' - AUTO - RECOMMEND_ON - 'ON' averageTemperature: type: number format: double controlledTemperature: type: number format: double baseLineTemperature: type: number format: double heatSourceTemperature: type: number format: double outdoorTemperature: type: number format: double operationStatus: type: string default: UNKNOWN enum: - UNKNOWN - HEATING - DRINKING_HOT_WATER - POOL_HEATING - EVU_LOCK - DEFROST - 'OFF' - EXTERNAL_SOURCE - COOLING energyHeating: type: number format: double energyDrinkingHotWater: type: number format: double required: - operationStatus x-readme-ref-name: HeatPumpMeasurementRaw - type: object properties: energyManagement: title: Energy Management Measurement type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured. strategyID: type: string description: 'True if the PV power is dynamically limited based on the available battery capacity. ' dynamicFeedInCurtailment: type: boolean description: 'True if the PV power is dynamically limited based on the available battery capacity. ' prognosisBasedBatteryCharging: type: boolean description: 'True if a forecast is used to determine the future feed-in into the batteries. ' activePowerSetpoint: type: integer format: int64 description: The setpoint the appliance should follow in mW. activePowerSetpointSystemicError: type: integer format: int64 description: 'The measured deviation from the setpoint for the active power value in mW. ' l1CurrentSetpoint: type: integer format: int64 description: Is the setpoint the appliance should follow in mA on phase 1. l2CurrentSetpoint: type: integer format: int64 description: Is the setpoint the appliance should follow in mA on phase 2. l3CurrentSetpoint: type: integer format: int64 description: Is the setpoint the appliance should follow in mA on phase 3. maxStateOfChargeAfterMaxFeedIn: type: integer format: int32 description: 'MaxStateOfChargeAfterMaxFeedIn is the max state of charge (0-100%) the battery can reach while considering the capacity needed to store the energy above max feed-in. (eBatMax - eBatOverFeedIn) * 100 / eBatMax. ' predictedEnergyOutput: type: integer format: int64 description: 'PredictedEnergyOutput is the predicted electrical energy output of this appliance in Wh based on the forecast model, including error adjustments. ' energyOverFeedInCumulatedDaily: type: integer format: int64 description: 'EnergyOverFeedInCumulatedDaily is the cumulated energy over the feed-in that is saved this day thanks to the energy management. This value is reported by the grid meter in Wh. ' x-readme-ref-name: EnergyManagementMeasurement x-readme-ref-name: CombinedMeasurement '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 '404': description: Entity Not found. 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '422': description: Validation failed. 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 - Validation description: 'Validation indicates that the request body contains fields which does not pass the validation. ' type: object required: - message - details example: message: Validation failed details: - email is not valid x-readme-ref-name: InvalidException '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 x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/appliances/applianceID/measurements" 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/appliances/applianceID/measurements \\\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/appliances/applianceID/measurements\"\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/appliances/applianceID/measurements', 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/appliances/applianceID/measurements\")\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/appliances/applianceID/measurements\")\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/appliances/applianceID/measurements")! 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/appliances/applianceID/measurements"); 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 /gateways/{gatewayID}/appliances/{applianceID}/measurements/energymanagement: get: operationId: getSystemEnergyManagementMeasurements summary: List Appliance's Energy Management Measurements description: 'Lists energy management measurements of an appliance over a period of time. Data points returned are emitted directly by the Energy Management System (EMS), therefore the resolution cannot be controlled. The granularity at which we store measurements depends on the EMS mode and configuration. The provided `interval` must not span more than 24 hours.' tags: - Appliance security: - HeaderAuth: - ApplianceMeasurementsRead 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: applianceID description: 'Unique identifier used to access an appliance. ' in: path required: true schema: type: string format: uuid example: bb2681ab-9526-49ca-bc52-a5f4ec366958 - 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 responses: '200': description: Energy Management Measurement returned. content: application/vnd.gridx.v2+json: schema: type: array items: title: Energy Management Measurement type: object properties: measuredAt: type: string format: date-time description: Time when the data was measured. strategyID: type: string description: 'True if the PV power is dynamically limited based on the available battery capacity. ' dynamicFeedInCurtailment: type: boolean description: 'True if the PV power is dynamically limited based on the available battery capacity. ' prognosisBasedBatteryCharging: type: boolean description: 'True if a forecast is used to determine the future feed-in into the batteries. ' activePowerSetpoint: type: integer format: int64 description: The setpoint the appliance should follow in mW. activePowerSetpointSystemicError: type: integer format: int64 description: 'The measured deviation from the setpoint for the active power value in mW. ' l1CurrentSetpoint: type: integer format: int64 description: Is the setpoint the appliance should follow in mA on phase 1. l2CurrentSetpoint: type: integer format: int64 description: Is the setpoint the appliance should follow in mA on phase 2. l3CurrentSetpoint: type: integer format: int64 description: Is the setpoint the appliance should follow in mA on phase 3. maxStateOfChargeAfterMaxFeedIn: type: integer format: int32 description: 'MaxStateOfChargeAfterMaxFeedIn is the max state of charge (0-100%) the battery can reach while considering the capacity needed to store the energy above max feed-in. (eBatMax - eBatOverFeedIn) * 100 / eBatMax. ' predictedEnergyOutput: type: integer format: int64 description: 'PredictedEnergyOutput is the predicted electrical energy output of this appliance in Wh based on the forecast model, including error adjustments. ' energyOverFeedInCumulatedDaily: type: integer format: int64 description: 'EnergyOverFeedInCumulatedDaily is the cumulated energy over the feed-in that is saved this day thanks to the energy management. This value is reported by the grid meter in Wh. ' x-readme-ref-name: EnergyManagementMeasurement x-readme-ref-name: EnergyManagementMeasurements '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 '404': description: Entity Not found. 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '422': description: Validation failed. 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 - Validation description: 'Validation indicates that the request body contains fields which does not pass the validation. ' type: object required: - message - details example: message: Validation failed details: - email is not valid x-readme-ref-name: InvalidException '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 x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/appliances/applianceID/measurements/energymanagement" 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/appliances/applianceID/measurements/energymanagement \\\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/appliances/applianceID/measurements/energymanagement\"\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/appliances/applianceID/measurements/energymanagement', 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/appliances/applianceID/measurements/energymanagement\")\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/appliances/applianceID/measurements/energymanagement\")\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/appliances/applianceID/measurements/energymanagement")! 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/appliances/applianceID/measurements/energymanagement"); 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 /gateways/{gatewayID}/appliances: get: operationId: listGatewayAppliances summary: List Gateway's Appliances description: 'Lists appliances that belong to the given gateway. Children appliances, e.g. those of hybrid inverters, are not included by default. To include them, `listAll` parameter must be set to `true`.' tags: - Appliance 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: listAll description: 'Boolean value to define if all the appliances must be listed. If absent or set to `false` child appliances of Hybrid Inverter would be skipped. ' in: query example: true schema: type: boolean default: false responses: '200': description: 'An array of appliances of up to `per_page` appliances. Each entry in the array is a separate appliance. If no appliance is available, the resulting array will be empty. ' content: application/vnd.gridx.v2+json: schema: 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 '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 '404': description: Gateway not found 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '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: - AppliancesRead x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/appliances" 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/appliances \\\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/appliances\"\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/appliances', 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/appliances\")\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/appliances\")\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/appliances")! 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/appliances"); 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 /gateways/{gatewayID}/appliances/{applianceID}: get: operationId: getGatewayAppliance summary: Retrieve an Appliance description: Retrieves the details of an existing appliance. tags: - Appliance 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: applianceID description: 'Unique identifier used to access an appliance. ' in: path required: true schema: type: string format: uuid example: bb2681ab-9526-49ca-bc52-a5f4ec366958 responses: '200': description: Returned Appliance. content: application/vnd.gridx.v2+json: schema: 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 '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 '404': description: Requested entity not found. 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '422': description: Validation failed. 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 - Validation description: 'Validation indicates that the request body contains fields which does not pass the validation. ' type: object required: - message - details example: message: Validation failed details: - email is not valid x-readme-ref-name: InvalidException '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: - AppliancesRead x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/appliances/applianceID" 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/appliances/applianceID \\\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/appliances/applianceID\"\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/appliances/applianceID', 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/appliances/applianceID\")\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/appliances/applianceID\")\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/appliances/applianceID")! 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/appliances/applianceID"); 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); ' patch: operationId: updateGatewayAppliance summary: Update an Appliance description: 'Updates the specific appliance by setting the values of the body parameters. Any parameters not provided will be left unchanged.' tags: - Appliance 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: applianceID description: 'Unique identifier used to access an appliance. ' in: path required: true schema: type: string format: uuid example: bb2681ab-9526-49ca-bc52-a5f4ec366958 requestBody: description: Partially updates an appliance. required: true content: application/json: schema: allOf: - title: Appliance Update description: 'ApplianceUpdate contains fields of an appliance that can be updated. ' type: object properties: 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 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 kind: description: 'Indicates the specific kind or role of the appliance. Only settable for appliances of type `INVERTER` or `METER`. For `INVERTER` appliances of kind `HYBRID`, it is not possible to update the kind, as this break the link to the `PV` and `BATTERY` children, making them orphans. If you wish to reset a `HYBRID` inverter, you can instead delete it and rescan, it will be recreated with `UNKNOWN` kind. ' type: string x-extensible-enum: - UNKNOWN - PV - PV_EXTERNAL - BATTERY - HYBRID - GRID - HEAT_PUMP - FUEL_CELL - HEAT_PUMP_EXTERNAL - EVSTATION - BTTP - HEATING - MISC - CLUSTER - WIND_TURBINE - AIR_CONDITIONER energySettings: 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 cryptoSettings: title: Crypto Settings description: 'Contains a list of crypto setting keys that are associated with the appliance. ' type: array items: type: object required: - key properties: key: description: Crypto key data that is accessible to the appliance. type: string x-readme-ref-name: AbstractCryptoSetting 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 evseID: description: The EVSE-ID related to the charge point. type: string x-readme-ref-name: EVSEID desiredState: title: Appliance State description: The desired state of the appliance. type: string enum: - SCANNED - CONNECTING - VERIFYING - UNTRUSTED - CONNECTED - DISCONNECTED x-readme-ref-name: DesiredStateUpdate 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 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: integer minimum: 0 maximum: 255 description: BitMask used to identify the channel. bitValue: type: integer minimum: 0 maximum: 255 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: WriteIODeviceInputChannel 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: integer minimum: 0 maximum: 255 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: integer minimum: 0 maximum: 255 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: WriteIODeviceOutputAction x-readme-ref-name: WriteIODeviceOutputChannel x-readme-ref-name: WriteIODeviceInformation pv: title: PV Information Update 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: PVInformationUpdate installationDate: type: string format: date-time description: Date when this appliance was installed. x-readme-ref-name: ApplianceUpdate - additionalProperties: false x-readme-ref-name: ApplianceUpdateStrict responses: '200': description: Updated appliance. content: application/vnd.gridx.v2+json: schema: 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 '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 '404': description: Requested entity not found. 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '409': description: Resource already exists 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 - Conflict description: 'Conflict indicates that the client is attempting to create a resource that already exists. ' type: object example: message: Resource already exists x-readme-ref-name: ConflictException '422': description: Validation failed. 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 - Validation description: 'Validation indicates that the request body contains fields which does not pass the validation. ' type: object required: - message - details example: message: Validation failed details: - email is not valid x-readme-ref-name: InvalidException '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: - AppliancesWrite x-code-samples: - lang: python label: Python source: "import requests\n\nurl = \"https://api.gridx.de/gateways/gatewayID/appliances/applianceID\"\n\nheaders = {\n \"accept\": \"application/vnd.gridx.v2+json\",\n \"content-type\": \"application/json\"\n}\n\nresponse = requests.patch(url, headers=headers)\n\nprint(response.text)" - lang: shell label: Shell source: "curl --request PATCH \\\n --url https://api.gridx.de/gateways/gatewayID/appliances/applianceID \\\n --header 'accept: application/vnd.gridx.v2+json' \\\n --header 'content-type: application/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/appliances/applianceID\"\n\n\treq, _ := http.NewRequest(\"PATCH\", url, nil)\n\n\treq.Header.Add(\"accept\", \"application/vnd.gridx.v2+json\")\n\treq.Header.Add(\"content-type\", \"application/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 = {\n method: 'PATCH',\n headers: {accept: 'application/vnd.gridx.v2+json', 'content-type': 'application/json'}\n};\n\nfetch('https://api.gridx.de/gateways/gatewayID/appliances/applianceID', 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/appliances/applianceID\")\n .patch(null)\n .addHeader(\"accept\", \"application/vnd.gridx.v2+json\")\n .addHeader(\"content-type\", \"application/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/appliances/applianceID\")\n .patch(null)\n .addHeader(\"accept\", \"application/vnd.gridx.v2+json\")\n .addHeader(\"content-type\", \"application/json\")\n .build()\n\nval response = client.newCall(request).execute()" - lang: javascript label: Swift source: "import Foundation\n\nlet url = URL(string: \"https://api.gridx.de/gateways/gatewayID/appliances/applianceID\")!\nvar request = URLRequest(url: url)\nrequest.httpMethod = \"PATCH\"\nrequest.timeoutInterval = 10\nrequest.allHTTPHeaderFields = [\n \"accept\": \"application/vnd.gridx.v2+json\",\n \"content-type\": \"application/json\"\n]\n\nlet (data, _) = try await URLSession.shared.data(for: request)\nprint(String(decoding: data, as: UTF8.self))" - lang: csharp label: C# source: 'using RestSharp; var options = new RestClientOptions("https://api.gridx.de/gateways/gatewayID/appliances/applianceID"); var client = new RestClient(options); var request = new RestRequest(""); request.AddHeader("accept", "application/vnd.gridx.v2+json"); request.AddHeader("content-type", "application/json"); var response = await client.PatchAsync(request); Console.WriteLine("{0}", response.Content); ' delete: operationId: deleteGatewayAppliance summary: Delete an Appliance description: Deletes an appliances. tags: - Appliance 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: applianceID description: 'Unique identifier used to access an appliance. ' in: path required: true schema: type: string format: uuid example: bb2681ab-9526-49ca-bc52-a5f4ec366958 responses: '204': description: Appliance has been deleted successfully. '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 '404': description: Requested entity not found. 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 - Not Found description: Not Found indicates that the entity was not found. example: message: Not Found x-readme-ref-name: NotFoundException '422': description: Validation failed. 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 - Validation description: 'Validation indicates that the request body contains fields which does not pass the validation. ' type: object required: - message - details example: message: Validation failed details: - email is not valid x-readme-ref-name: InvalidException '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: - AppliancesWrite x-code-samples: - lang: python label: Python source: 'import requests url = "https://api.gridx.de/gateways/gatewayID/appliances/applianceID" headers = {"accept": "application/vnd.gridx.v2+json"} response = requests.delete(url, headers=headers) print(response.text)' - lang: shell label: Shell source: "curl --request DELETE \\\n --url https://api.gridx.de/gateways/gatewayID/appliances/applianceID \\\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/appliances/applianceID\"\n\n\treq, _ := http.NewRequest(\"DELETE\", 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: 'DELETE', headers: {accept: 'application/vnd.gridx.v2+json'}};\n\nfetch('https://api.gridx.de/gateways/gatewayID/appliances/applianceID', 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/appliances/applianceID\")\n .delete(null)\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/appliances/applianceID\")\n .delete(null)\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/appliances/applianceID")! var request = URLRequest(url: url) request.httpMethod = "DELETE" 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/appliances/applianceID"); var client = new RestClient(options); var request = new RestRequest(""); request.AddHeader("accept", "application/vnd.gridx.v2+json"); var response = await client.DeleteAsync(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