openapi: 3.0.2 info: title: BSB-LAN API version: '2.4' description: BSB-LAN JSON API Specification termsOfService: '' contact: name: BSB-LAN url: 'https://github.com/fredlcore/BSB-LAN' servers: - url: http://bsb-lan.local tags: - name: 'General' - name: 'Parameter' - name: 'Category' - name: 'Configuration' paths: /JB: get: summary: List all writeable parameters description: '' operationId: listWritableParametersUsingGET tags: - 'Parameter' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/WritableParameterMap' /JB!{deviceId}: get: summary: List all writeable parameters () description: '' operationId: listWritableParametersUsingGETfromId tags: - 'Parameter' parameters: - name: deviceId in: path required: true description: Specify destination ID. explode: false schema: type: number format: integer example: 0, 1 responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/WritableParameterMap' /JC: post: summary: List parameter definitions description: '' operationId: listParameterDefinitionsUsingPOST tags: - 'Parameter' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ParameterFilterList' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParameterDefinitionMap' /JC={parameterIds}: get: summary: 'List parameter definitions' description: '' operationId: listParameterDefinitionsUsingGET tags: - 'Parameter' parameters: - name: parameterIds in: path required: true description: One or more comma separated parameter numbers schema: type: string responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParameterDefinitionMap' /JI: get: summary: 'Query configuration of BSB-LAN' description: '' operationId: getInfo tags: - 'General' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GeneralInfo' /JK={categoryId}: get: summary: 'Query a specific category' description: '' operationId: getCategory tags: - 'Category' parameters: - name: categoryId in: path required: true description: 'ID of category' schema: type: number format: integer responses: '401': description: 'Unauthorized' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParameterDefinitionMap' /JK=ALL: get: summary: 'Get all categories' description: '' operationId: getCategories tags: - 'Category' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CategoryMap' /JL: get: summary: 'Get all BSB-LAN configuration values' description: '' operationId: getConfiguration tags: - 'Configuration' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConfigurationList' /JQ: post: summary: List parameters description: '' operationId: listParametersPost tags: - 'Parameter' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ParameterFilterList' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParameterMap' /JQ={parameterIds}: get: summary: List parameters description: '' operationId: listParameters tags: - 'Parameter' parameters: - name: parameterIds in: path required: true description: One or more comma separated parameter ids schema: type: string example: 700,710 responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParameterMap' /JR: post: summary: 'Queries the reset/default-value of parameter' description: 'Within the integrated operational unit of the heating system there are reset options available for some parameters. A reset is done by asking the system for the reset value and setting it afterwards (JSON: via/JS).' operationId: getResetValuePost tags: - 'Parameter' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ParameterFilterList' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ResetValueMap' /JR={parameterIds}: get: summary: 'Queries the reset/default-value of parameter' description: 'Within the integrated operational unit of the heating system there are reset options available for some parameters. A reset is done by asking the system for the reset value and setting it afterwards (JSON: via/JS).' operationId: getResetValue tags: - 'Parameter' parameters: - name: parameterIds in: path required: true description: One or more comma separated parameter ids schema: type: string responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ResetValueMap' /JS: post: summary: 'Write parameter value' description: '' operationId: writeParameter tags: - 'Parameter' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ParameterWrite' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ParameterWriteResult' /JV: get: summary: Queries the JSON-API version description: '' operationId: getApiVersion tags: - 'General' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiVersion' /JW: post: summary: 'Write new BSB-LAN configuration values' description: '' operationId: writeConfiguration tags: - 'Configuration' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfigurationWriteList' responses: '401': description: Unauthorized '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConfigurationWriteResultMap' components: schemas: ApiVersion: title: ApiVersion description: 'Object containing API Version' type: object properties: api_version: type: string example: api_version: '2.0' Category: title: Category description: 'Category definition, contains min/max parameter numbers as well as information on device family, variant, and destination ID and model name.' type: object properties: name: description: Name of category type: string min: format: integer description: Min parameter ID for category type: number max: format: integer description: Max parameter ID for category type: number dev_fam: format: integer description: Device family associated with this category type: number dev_var: format: integer description: Device variant associated with this category type: number dev_id: format: integer description: Destination device ID associated with this category type: number dev_name: format: integer description: Model name associated with this category type: number example: name: 'Uhrzeit und Datum' min: 0 max: 6 dev_fam: 90 dev_var: 239 dev_id: 0 dev_name: "RVS63.283/200" CategoryMap: title: Categories description: 'HashMap of multiple categories with category ID as key.' type: object additionalProperties: $ref: '#/components/schemas/Category' example: '0': name: 'Uhrzeit und Datum' min: 0 max: 6 dev_fam: 90 dev_var: 239 dev_id: 0 dev_name: "RVS63.283/200" '1': name: 'Bedieneinheit' min: 20 max: 70 dev_fam: 97 dev_var: 136 dev_id: 1 dev_name: "LMU7" Configuration: title: Configuration description: 'Details of a BSB-LAN configuration object' type: object properties: parameter: description: 'Configuration ID' type: string type: description: | Data type 0 - CDT_VOID // byte array (for internal using. Never sent through JSON) 1 - CDT_BYTE //unsigned byte. can be various format (text, switch, dropdown) 2 - CDT_UINT16 //CPI_TEXT field with format for unsigned integer 3 - CDT_UINT32 //CPI_TEXT field with format for unsigned long integer 4 - CDT_STRING //CPI_TEXT field 5 - CDT_MAC //CPI_TEXT field with format for MAC input/output 6 - CDT_IPV4 //CPI_TEXT field with format for IPv4 input/output 7 - CDT_PROGNRLIST //CPI_TEXT field with format for programs list input/output 8 - CDT_MAXDEVICELIST //CPI_TEXT field with format for MAX! devices list input/output 9 - CDT_DHTBUS //CPI_TEXT field with format for DHT bus type: number format: integer minimum: 0 maximum: 9 format: description: | HTML Input type 0 - none 1 - text field 2 - switch 3 - dropdown type: number format: integer minimum: 0 maximum: 3 category: description: 'Category of configuration object' type: string name: description: 'Name of configuration object' type: string value: description: 'Value of configuration object' type: string possibleValues: $ref: '#/components/schemas/PossibleValueList' example: parameter: '0' type: 1 format: 2 category: 'CAT_GENERAL_TEXT' name: 'CF_USEEEPROM_TEXT' value: '150' possibleValues: [ { enumValue: '105', desc: 'MENU_TEXT_OFF' }, { enumValue: '150', desc: 'MENU_TEXT_ON' } ] ConfigurationList: title: ConfigurationList description: 'List of multiple BSB-LAN configuration objects' type: array items: $ref: '#/components/schemas/Configuration' example: [ { parameter: '0', type: 1, format: 2, category: 'CAT_GENERAL_TEXT', name: 'CF_USEEEPROM_TEXT', value: '150', possibleValues: [ { enumValue: '105', desc: 'MENU_TEXT_OFF' }, { enumValue: '150', desc: 'MENU_TEXT_ON' } ] }, { parameter: '6', type: 1, format: 3, category: 'CAT_GENERAL_TEXT', name: 'CF_BUSTYPE_TEXT', value: '0', possibleValues: [ { enumValue: '0', desc: 'BSB' }, { enumValue: '1', desc: 'LPB' }, { enumValue: '2', desc: 'PPS' } ] }, ] ConfigurationWriteResult: title: ConfigurationWriteResult description: 'Write result of BSB-LAN configuration object' type: object properties: status: description: | Write status 1 - OK 2 - Not found type: number format: integer minimum: 1 maximum: 2 example: status: 1 ConfigurationWriteResultMap: title: ConfigurationWriteResultMap description: 'Multiple write results of BSB-LAN configurations as hash map with parameter ID as key' type: object additionalProperties: $ref: '#/components/schemas/ConfigurationWriteResult' example: - '0': {status: 1} - '6': {status: 0} ConfigurationWrite: title: ConfigurationWrite description: 'Write BSB-LAN configuration object' type: object properties: parameter: description: 'Parameter ID' type: number format: float value: description: 'New value of configuration parameter' type: string required: - parameter - value example: parameter: 0 value: '150' ConfigurationWriteList: title: ConfigurationWriteList description: 'Write multiple BSB-LAN configuration objects' type: array items: $ref: '#/components/schemas/ConfigurationWrite' example: [{parameter: 0, value: '150'}, {parameter: 6, value: "0"}] GeneralInfo: title: GeneralInfo description: 'Detailed information about the BSB-LAN device configuration and status.' type: object properties: name: type: string description: 'Name of the BSB-LAN device' version: type: string description: 'Firmware version of the device' hardware: type: string description: 'Type of hardware' freeram: type: number format: integer description: 'Amount of free RAM in bytes' uptime: type: number format: integer description: 'Uptime of the device in seconds' MAC: type: string description: 'MAC address of the device' pattern: '^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$' freespace: type: number format: integer description: 'Free flash memory on the device' bus: type: string description: 'Selected bus type (BSB, LPB or PPS)' buswritable: type: number format: integer description: 'Indicates if the bus is writable (0 = no, 1 = yes (user), 2 = yes (technician))' busaddr: type: number format: integer description: 'Bus address of the device' busdest: type: number format: integer description: 'Destination device address' busdevices: description: 'List of devices connected to the bus' type: array items: $ref: '#/components/schemas/BusDevice' monitor: type: number format: integer description: 'Monitor output status' verbose: type: number format: integer description: 'Verbose mode status' onewirebus: type: number format: integer description: 'Pin number for the OneWire bus' onewiresensors: type: number format: integer description: 'Number of OneWire sensors connected' dhtbus: type: array description: 'DHT bus configuration pins' items: $ref: '#/components/schemas/PinList' loggingmode: type: number format: integer description: 'Logging mode of the device. Multiple modes possible. 0 - disabled, 1 - write values to SD card, 2 - write 24h averages to SD card, 4 - send values to MQTT, 8 - only log parameters to MQTT, 16 - send values to UDP' loginterval: type: number format: integer description: 'Log interval in seconds' logged: type: array description: 'List of logged parameters' items: $ref: '#/components/schemas/ParameterList' averages : type: array description: 'List of logged parameters' items: $ref: '#/components/schemas/ParameterList' example: name: 'BSB-LAN' version: '4.2.29-20241130021332' hardware: 'ESP32' freeram: 217508 uptime: 4961655 MAC: 'AC:67:B2:46:57:F4' freespace: 0 bus: 'LPB' buswritable: 0 busaddr: 66 busdest: 0 busdevices: - dev_id: 0 dev_fam: 90 dev_var: 239 dev_serial: 40528 dev_name: 'RVS63.283/200' - dev_id: 1 dev_fam: 97 dev_var: 136 dev_serial: 1409090147 dev_name: 'LMU7' monitor: 0 verbose: 1 onewirebus: -1 onewiresensors: 0 dhtbus: - pin: -1 - pin: -1 - pin: -1 - pin: -1 - pin: -1 - pin: -1 - pin: -1 - pin: -1 - pin: -1 - pin: -1 loggingmode: 4 loginterval: 0 logged: - parameter: 8326 destination: 1 - parameter: 8951 destination: -1 - parameter: 8952 destination: -1 - parameter: 720 destination: -1 averages: - parameter: 8326 destination: 1 - parameter: 8951 destination: -1 - parameter: 8952 destination: -1 - parameter: 720 destination: -1 BusDevice: type: object properties: dev_id: type: number format: integer description: Destination device ID dev_fam: type: number format: integer description: Device family dev_var: type: number format: integer description: Device variant dev_oc: type: number format: integer description: Device object catalog version dev_serial: type: number format: integer description: Device serial number dev_name: type: string description: Controler model ParameterNotation: title: ParameterNotation description: '' type: object properties: parameter: type: number format: float description: Parameter number destination: type: number format: integer description: Destination device ID, -1 for default device example: parameter: 8700 destination: 1 ParameterList: title: ParameterList description: '' type: array items: $ref: '#/components/schemas/ParameterNotation' example: [{ "parameter": 8326, "destination": 1 }, { "parameter": 8951, "destination": -1 }] Parameter: title: Parameter description: 'Contains the value of a parameter and some more details' type: object properties: name: description: 'Name of the parameter' type: string dataType_family: $ref: '#/components/schemas/ParameterTypeName' dataType_name: $ref: '#/components/schemas/DataTypeName' destination: type: number format: integer error: $ref: '#/components/schemas/Error' value: description: 'Value of the parameter (--- for disabled / not available)' type: string desc: description: 'Description of the value' type: string payload: description: 'Raw payload data from bus telegram' type: string precision: $ref: '#/components/schemas/Precision' dataType: $ref: '#/components/schemas/ParameterType' readwrite: $ref: '#/components/schemas/ReadWrite' unit: description: 'Unit of the parameter' type: string example: name: 'Betriebsart' dataType_name: 'ENUM' dataType_family: 'ENUM' destination: 0 error: 0 value: '1' desc: 'Automatik' payload: '0001' dataType: 1 readwrite: 0 unit: '' ParameterMap: title: ParameterMap description: 'HashMap of parameters as with parameter ID as key' type: object additionalProperties: $ref: '#/components/schemas/Parameter' example: '700': name: 'Betriebsart' dataType_family: 'ENUM' dataType_name: 'ENUM' destination: 0 error: 0 value: '1' desc: 'Automatic' dataType: 1 readwrite: 0 unit: '' ParameterDefinition: title: ParameterDefinition description: 'Object containing parameter definition' type: object properties: name: description: 'Name of the parameter' type: string destination: type: number format: integer possibleValues: $ref: '#/components/schemas/PossibleValueList' isswitch: description: | Parameter is a switch 0 - No 1 = Yes, ONOFF or YESNO type: number format: integer minimum: 0 maximum: 1 readwrite: $ref: '#/components/schemas/ReadWrite' dataType: $ref: '#/components/schemas/ParameterType' dataType_family: $ref: '#/components/schemas/ParameterTypeName' dataType_name: $ref: '#/components/schemas/DataTypeName' unit: description: 'Unit of the parameter' type: string example: name: 'Betriebsart' possibleValues: [{enumValue: 0, desc: 'Schutzbetrieb'}, {enumValue: 1, desc: 'Automatik'}] isswitch: 0 dataType: 1 readonly: 0 unit: '' ParameterDefinitionMap: title: ParameterDefinitionMap description: 'HashMap of parameter definition with parameter ID as key' type: object additionalProperties: $ref: '#/components/schemas/ParameterDefinition' example: '700': name: 'Betriebsart' dataType_family: "ENUM" dataType_name: "ENUM" destination: 0 possibleValues: [{"enumValue": 0, "desc": "Schutzbetrieb" }, { "enumValue": 1, "desc": "Automatik" }] isswitch: 0 dataType: 1 readwrite: 0 unit: '' ParameterFilter: title: ParameterFilter description: 'Filter for requesting parameter' type: object properties: parameter: type: number format: float destination: type: number format: integer description: Destination device ID. Use -1 for default destination. required: - parameter example: parameter: 700 destination: -1 ParameterFilterList: title: ParameterFilterList description: 'List of filters to request multiple parameters' type: array items: $ref: '#/components/schemas/ParameterFilter' example: [{parameter: '700', destination: 0}, {parameter: '701', destination: -1}] ParameterWrite: title: ParameterWrite description: 'Object for updating parameter value' type: object properties: parameter: description: 'Id of parameter' type: number format: float value: description: 'New parameter value' type: string type: $ref: '#/components/schemas/WriteType' destination: description: 'Destination device' type: number format: integer required: - Parameter - Value - Type example: '700': parameter: 700 value: '1' destination: 0 type: 1 ParameterWriteResult: title: ParameterWriteResult description: 'Conains result of write request' type: object properties: parameter: description: 'Id of parameter' type: number format: float status: description: | Status of write request 0 - Error 1 - OK 2 - parameter read-only type: number format: integer minimum: 0 maximum: 2 destination: description: 'Destination device' type: number format: integer example: '700': status: 1 destination: 0 PossibleValue: title: PossibleValue description: 'Contains possible Enum Values' type: object properties: enumValue: description: Enum Value type: number format: integer desc: description: Description of Enum Value type: string example: enumValue: 1 desc: 'Automatik' PossibleValueList: title: PossibleValueList description: 'List of possible values' type: array items: $ref: '#/components/schemas/PossibleValue' example: [{enumvalue: 0, desc: 'Schutzbetrieb'}, {enumvalue: 1, desc: 'Automatik'}] Precision: title: Precision description: 'Digits after the decimal dot' type: number example: precision: 0.1 ResetValue: title: ResetValue description: 'Reset value of parameter' type: object properties: error: $ref: '#/components/schemas/Error' value: description: 'Reset value' type: string destination: type: number format: integer example: error: 0 value: '3' destination: 0 ResetValueMap: title: ResetValueMap description: 'HashMap of reset values with parameter ID as key' type: object additionalProperties: $ref: '#/components/schemas/ResetValue' example: '700': error: 0 value: '3' destination: 0 WritableParameterMap: title: WritableParameterMap description: 'HashMap of writable parameters with parameter information as key' type: object additionalProperties: $ref: '#/components/schemas/WritableParameter' example: '70': parameter: 70 value: '4.2' destination: 1 type: 1 '130': parameter: 130 value: '65535' destination: 0 type: 1 WritableParameter: title: WritableParameter description: 'A parameter which can be written' type: object properties: parameter: description: 'Parameter number' type: number format: float value: description: 'Value to be set' type: string destination: description: 'Device ID of destination' type: number format: integer type: $ref: '#/components/schemas/WriteType' example: parameter: 70 value: '4.2' destination: 0 type: 1 Pins: title: Pins description: 'Pins' type: object properties: pin: description: 'Pin number' type: number format: integer example: pin: 42 PinList: title: PinList description: '' type: array items: $ref: '#/components/schemas/Pins' example: [{"pins": 42}, {"pins": -1}] Error: title: Error description: | Current state of parameter value 0 - ok 7 - parameter not supported 1..255 - LPB/BSB bus errors 256 - decoding error 257 - unknown command 258 - not found 259 - no enum str 260 - unknown type 261 - query failed 262 - too few/many arguments in SET command 263 - invalid category type: number format: float minimum: 0 maximum: 263 IsReadOnly: title: IsReadOnly description: | Parameter is readonly 0 - read/write 1 - readonly type: number minimum: 0 maximum: 1 format: integer deprecated: true DataTypeName: title: DataTypeName description: Value type (TEMP, HOUR etc.). See optbl[] entries type: string ParameterTypeName: title: ParameterTypeName description: | Data type of parameter value: VALS - plain numerical value ENUM - value representing a selectable options BITS - bit value containing multiple settings HHMM - hour:minute DTTM - date and time DDMM - day and month STRN - string DWHM - PPS time (day of week, hour:minute) TMPR - time program THMS - time (hours:minute:seconds) type: string ParameterType: title: ParameterType description: | Data type of parameter value: 0 - Number ("1", "20.5", "---" for value not available) 1 - ENUM (Integer value of Enum "2") 2 - Bit value ("01000101") 3 - Weekday 4 - Hour:Minute 5 - Date and time ("09.01.2021 12:42:02") 6 - Day and month ("25.10") 7 - String 8 - PPS time (day of week, hour:minute) type: number format: integer minimum: 0 maximum: 8 ReadWrite: title: ReadWrite description: | 0 - read/write 1 - readonly 2 - write only type: number format: integer minimum: 0 maximum: 2 WriteType: title: WriteType description: | 0 - INF 1 - SET type: number format: integer minimum: 0 maximum: 1 securitySchemes: basicAuth: type: http scheme: basic security: - basicAuth: []