Does anyone have some documentation on the local API that was amoung the added features in FW update 4.4.7 for Nibe heatpumps S series ?
I have activated the API in installer meny, But need the documentation for the methods, params.
Reference :
Might try to follow this docs : Swagger UI
hi!
Unfortunately, I do not have additional information. I tried enabling the Local REST API in menu 7.5.15 and wanted to check the REST API in my browser via the adress shown by the SMO S40. No matter how I changed the settings (with/without username/password, enable or disable the “allow remote IPs to connect”, set API to read/write), I always got a timeout when trying out https://[SMO S40 IP]:8443/
Have you been able to at least access the API?
Thanks for the reply, il give it a try, il let u know how it goes !.
Hello, ive talked to Nibe, there is an issue with the new update , its the Firewall on the heatpump , its blocking the communication to the Local api.
There will be an update in early october to fix this.
The api will be documentet as an webpage, this webserver containing the needed info to interact with the api, it will be accessable when u use a web browser to target the heatpumps LAN ip address.
I installed the update and can connect now, however no openapi, but visual code AI generated this openapi from the webpage, seems to work in Postman 
openapi: 3.0.3
info:
title: Local Device REST API
description: The local API for your product which allows you to remotely monitor and control the device.
version: 1.0.0
contact:
name: API Support
license:
name: MIT
servers:
- url: https://192.168.188.51:8443
description: Local device server (HTTPS)
- url: http://192.168.188.51:8080
description: Local device server (HTTP)
security:
- basicAuth: []
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Basic HTTP authentication using username and password
schemas:
Device:
type: object
properties:
deviceIndex:
type: integer
description: Device index
aidMode:
type: string
enum:
- "off"
- "on"
description: Aid mode setting
smartMode:
type: string
enum:
- "normal"
- "away"
description: Smart mode setting
product:
$ref: '#/components/schemas/Product'
Product:
type: object
properties:
serialNumber:
type: string
description: Device serial number
name:
type: string
description: Product name
manufacturer:
type: string
description: Manufacturer name
firmwareId:
type: string
description: Firmware identifier
DevicesResponse:
type: object
properties:
devices:
type: array
items:
$ref: '#/components/schemas/Device'
AidModeSet:
type: object
required:
- aidMode
properties:
aidMode:
type: string
enum:
- "off"
- "on"
description: Aid mode to set
SmartModeSet:
type: object
required:
- smartMode
properties:
smartMode:
type: string
enum:
- "normal"
- "away"
description: Smart mode to set
Alarm:
type: object
properties:
alarmId:
type: integer
description: Unique alarm identifier
description:
type: string
description: Alarm description
header:
type: string
description: Alarm header/title
severity:
type: integer
description: Alarm severity level
time:
type: string
description: UTC ISO date and time
example: "2019-05-02 13:38:06"
equipName:
type: string
description: Equipment name
AlarmsResponse:
type: object
properties:
alarms:
type: array
items:
$ref: '#/components/schemas/Alarm'
PointMetadata:
type: object
properties:
type:
type: string
enum:
- "metadata"
description: Type of the object (always "metadata")
variableId:
type: integer
description: Variable ID
variableType:
type: string
enum:
- "integer"
- "string"
- "binary"
- "time"
- "date"
- "floating-point"
- "unknown"
description: Variable type
variableSize:
type: string
enum:
- "s8"
- "s16"
- "s32"
- "u8"
- "u16"
- "u32"
- "f4"
- "f8"
- "unknown"
description: Variable size
unit:
type: string
description: Unit name
modbusRegisterType:
type: string
enum:
- "MODBUS_INPUT_REGISTER"
- "MODBUS_HOLDING_REGISTER"
- "MODBUS_NO_REGISTER"
- "ERR_UNKNOWN"
description: Modbus register type
shortUnit:
type: string
description: Short unit name
isWritable:
type: boolean
description: Whether the value is writable
divisor:
type: integer
description: Divisor for the integer value
decimal:
type: integer
description: Number of decimal places
modbusRegisterID:
type: integer
description: Modbus register ID
minValue:
type: integer
description: Minimum integer value
maxValue:
type: integer
description: Maximum integer value
intDefaultValue:
type: integer
description: Default integer value
change:
type: integer
description: Change threshold for integer value
stringDefaultValue:
type: string
description: Default string value
DataValue:
type: object
properties:
type:
type: string
enum:
- "datavalue"
description: Type of the object (always "datavalue")
isOk:
type: boolean
description: Whether the value is OK
variableId:
type: integer
description: Variable ID
integerValue:
type: integer
description: Integer value
stringValue:
type: string
description: String value
Point:
type: object
properties:
title:
type: string
description: Title of the point
description:
type: string
description: Description of the point
metadata:
$ref: '#/components/schemas/PointMetadata'
datavalue:
$ref: '#/components/schemas/DataValue'
PointsResponse:
type: object
additionalProperties:
$ref: '#/components/schemas/Point'
description: Map of variable IDs to Point objects
PointsPatchItem:
type: array
items:
$ref: '#/components/schemas/DataValue'
PointsPatchResponse:
type: object
additionalProperties:
type: string
enum:
- "modified"
- "error: no such param"
- "error: read only value"
description: Map of variable IDs to modification status
Error:
type: object
properties:
error:
type: string
description: Error message
paths:
/api/v1/devices:
get:
tags:
- DeviceInformation
summary: getDevices
description: Fetch the status of all devices hosted on the API endpoint
security:
- basicAuth: []
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/DevicesResponse'
/api/v1/devices/{deviceId}:
get:
tags:
- DeviceInformation
summary: getDevice
description: Fetch the status of a single device
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/devices/{deviceId}/aidmode:
post:
tags:
- DeviceInformation
summary: setAidMode
description: Change Aid mode on device
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
requestBody:
description: JSON with a state to be set
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AidModeSet'
responses:
'200':
description: success message
'400':
description: error description (missing some input/bad input)
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/devices/{deviceId}/smartmode:
post:
tags:
- DeviceInformation
summary: setSmartMode
description: Change Smart mode on device
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
requestBody:
description: JSON with a state to be set
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SmartModeSet'
responses:
'200':
description: success message
'400':
description: error description (missing some input/bad input)
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/devices/{deviceId}/notifications:
get:
tags:
- Notifications
summary: getNotifications
description: List ongoing alarms/notifications on the system
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AlarmsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
tags:
- Notifications
summary: resetNotifications
description: Reset all alarms/notifications on the system
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
responses:
'204':
description: Successful operation
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Alarms reset is not supported or not enabled on device
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal error when requesting alarms reset
/api/v1/devices/{deviceId}/points/{pointId}:
get:
tags:
- Points
summary: getPoint
description: Retrieve sensor or setting data for point with given ID
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: pointId
in: path
required: true
description: Point ID
schema:
type: integer
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
responses:
'200':
description: JSON document, containing single key-value pair where key is point ID
content:
application/json:
schema:
$ref: '#/components/schemas/Point'
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/devices/{deviceId}/points:
get:
tags:
- Points
summary: getPoints
description: Retrieve all current sensor and setting data
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
responses:
'200':
description: list of all points with values
content:
application/json:
schema:
$ref: '#/components/schemas/PointsResponse'
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
tags:
- Points
summary: patchPoints
description: Change value for specific point(s)
security:
- basicAuth: []
parameters:
- name: deviceId
in: path
required: true
description: Serial number can be used as well as device index
schema:
type: string
- name: Authorization
in: header
required: true
description: Authorization token
schema:
type: string
requestBody:
description: JSON map with point id's and corresponding values to be set
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PointsPatchItem'
responses:
'200':
description: List of all points status of update
content:
application/json:
schema:
$ref: '#/components/schemas/PointsPatchResponse'
'401':
description: Authorization token invalid or missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Wrong deviceId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- name: DeviceInformation
description: Device information and control operations
- name: Notifications
description: Alarm and notification management
- name: Points
description: Sensor data and settings management
Got an update from nibe. local api is still unreachable 
EDIT: It works, used the wrong port
This is a goldmine! Much better than modbus! I wrote the JSON and recived a 406KB with 870 total data points of which 487 are WRITABLE BOOM!
Yes, the API is now reachable.
/api/v1/devices/0/points lists 496 writable points and 751 non-writable.
Here’s an example
"4": {
"title": "AktuÂelle AuĂźenÂluftÂtempeÂratur (BT1)",
"description": "",
"metadata": {
"type": "metadata",
"variableId": 4,
"variableType": "integer",
"variableSize": "s16",
"unit": "°C",
"modbusRegisterType": "MODBUS_INPUT_REGISTER",
"shortUnit": "°",
"isWritable": false,
"divisor": 10,
"decimal": 1,
"modbusRegisterID": 1,
"minValue": 0,
"maxValue": 0,
"intDefaultValue": 0,
"change": 5,
"stringDefaultValue": ""
},
"value": {
"type": "datavalue",
"isOk": true,
"variableId": 4,
"integerValue": 100,
"stringValue": ""
}
},
"5": {
"title": "Vorlauf (EP23-BT2)",
"description": "",
"metadata": {
"type": "metadata",
"variableId": 5,
"variableType": "integer",
"variableSize": "s16",
"unit": "°C",
"modbusRegisterType": "MODBUS_INPUT_REGISTER",
"shortUnit": "°",
"isWritable": false,
"divisor": 10,
"decimal": 1,
"modbusRegisterID": 2,
"minValue": 0,
"maxValue": 0,
"intDefaultValue": 0,
"change": 5,
"stringDefaultValue": ""
},
"value": {
"type": "datavalue",
"isOk": true,
"variableId": 5,
"integerValue": -32768,
"stringValue": ""
}
},
"6": {
"title": "Vorlauf (EP22-BT2)",
"description": "",
"metadata": {
"type": "metadata",
"variableId": 6,
"variableType": "integer",
"variableSize": "s16",
"unit": "°C",
"modbusRegisterType": "MODBUS_INPUT_REGISTER",
"shortUnit": "°",
"isWritable": false,
"divisor": 10,
"decimal": 1,
"modbusRegisterID": 3,
"minValue": 0,
"maxValue": 0,
"intDefaultValue": 0,
"change": 5,
"stringDefaultValue": ""
},
"value": {
"type": "datavalue",
"isOk": true,
"variableId": 6,
"integerValue": -32768,
"stringValue": ""
}
I think i don’t really get how to connect to the api.
Can someone share a “wget” command that should work?
wget <IP-OF-SMOS40>/api/v1/devices/0/points
does not work for me
Try using a browser first.
Depending on your settings, you might need to add a port as well and use https.
For me it goes like this:
open https://NIBE-IP:8443 in the browser, which then prompts for authentification (as set in the heatpump’s menu). After successfull authentication, you get to a nice documentation with examples using curl. Keep in mind, that you can easily open the URLs in the browser as well (at least the “GET” stuff).
I had to fiddle a bit with the settings in the SMO S40, but now it works with the browser. I’ll will be able to work from there. Thanks a lot.
Is access to the API 100% local?
In other words will it work without any kind of MyUplink subscription, or do you then have limited access?
I don’t have a MyUplink subscription and it works fine fully local. Lots of data points (seem the same like the modbus ones).
I tried to update a data point with patch but I just get a 200 reply with the unmodified data point.
Request
curl --location --request PATCH 'https://192.168.1.19:8443/api/v1/devices/0/points' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic afdsffssdf==' \
--data '[
{
"type": "datavalue",
"isOkz": true,
"variableId": 5204,
"integerValue": 100,
"stringValue": ""
}
]'
Reply 200
{
"5204": {
"title": "Max. interÂnal addiÂtional heat SG Ready",
"description": "",
"metadata": {
"type": "metadata",
"variableId": 5204,
"variableType": "integer",
"variableSize": "s16",
"unit": "kW",
"modbusRegisterType": "MODBUS_HOLDING_REGISTER",
"shortUnit": "kW",
"isWritable": true,
"divisor": 100,
"decimal": 1,
"modbusRegisterID": 1052,
"minValue": 0,
"maxValue": 900,
"intDefaultValue": 700,
"change": 50,
"stringDefaultValue": ""
},
"value": {
"type": "datavalue",
"isOk": true,
"variableId": 5204,
"integerValue": 50,
"stringValue": ""
}
}
}
I have problems getting onto my SMO S40.
API ist activated username and PW set but I do not get a login at the https afress shown.
Could you help me by explaining what fiddling was necessary?
Thanx!
Hannes