Skip to content

Commit 1b2ff57

Browse files
nadlechSICKAGnadlechSICKAG
committed
docs: update openapi.yaml with enhanced property descriptions and version bump to 1.0.2
1 parent 81610c8 commit 1b2ff57

File tree

1 file changed

+155
-26
lines changed

1 file changed

+155
-26
lines changed

‎docs/openapi.yaml‎

Lines changed: 155 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
openapi: 3.0.0
1+
openapi: 3.0.0
22
info:
33
title: Device API
44
description: API for managing device properties and HA MQTT integration.
5-
version: 1.0.1
5+
version: 1.0.2
66

77
servers:
88
- url: http://<server-ip>
@@ -38,129 +38,203 @@ paths:
3838
description: Product name.
3939
properties:
4040
type: object
41-
description: Device runtime properties.
41+
description: Device runtime properties (read-only unless noted).
4242
properties:
4343
heatState:
4444
type: integer
45-
description: '0: Not heating, 1: Heating.'
45+
description: 'Heating state. 0: Not heating, 1: Heating.'
4646
packInputPower:
4747
type: integer
48+
description: 'Battery discharge power (W).'
4849
outputPackPower:
4950
type: integer
51+
description: 'Battery charge power (W).'
5052
outputHomePower:
5153
type: integer
54+
description: 'Output power to home (W).'
5255
remainOutTime:
5356
type: integer
57+
description: 'Remaining discharge time (min).'
5458
packState:
5559
type: integer
56-
description: '0: Standby, 1: Charging, 2: Discharging.'
60+
description: 'Pack state. 0: Standby, 1: Charging, 2: Discharging.'
61+
packNum:
62+
type: integer
63+
description: 'Number of battery packs.'
5764
electricLevel:
5865
type: integer
66+
description: 'Average state of charge across all packs (%). Range: 0-100.'
5967
gridInputPower:
6068
type: integer
69+
description: 'Grid input power (W).'
6170
solarInputPower:
6271
type: integer
72+
description: 'Total PV input power (W).'
6373
solarPower1:
6474
type: integer
75+
description: 'PV channel 1 power (W).'
6576
solarPower2:
6677
type: integer
78+
description: 'PV channel 2 power (W).'
79+
solarPower3:
80+
type: integer
81+
description: 'PV channel 3 power (W).'
82+
solarPower4:
83+
type: integer
84+
description: 'PV channel 4 power (W).'
85+
solarPower5:
86+
type: integer
87+
description: 'PV channel 5 power (W).'
88+
solarPower6:
89+
type: integer
90+
description: 'PV channel 6 power (W).'
6791
pass:
6892
type: integer
93+
description: 'Pass-through state. 0: Off, 1: On.'
6994
reverseState:
7095
type: integer
96+
description: 'Reverse flow state. 0: Off, 1: On.'
7197
socStatus:
7298
type: integer
99+
description: 'SOC calibration status. 0: Normal, 1: Calibrating.'
73100
hyperTmp:
74101
type: integer
102+
description: 'Enclosure temperature (0.1 K stored; use same conversion as maxTemp).'
75103
dcStatus:
76104
type: integer
105+
description: 'DC state. Range: 0-2.'
77106
pvStatus:
78107
type: integer
108+
description: 'PV state. 0: Off, 1: On.'
79109
acStatus:
80110
type: integer
111+
description: 'AC state. Range: 0-2.'
81112
dataReady:
82113
type: integer
114+
description: 'Data ready flag. 0: Not ready, 1: Ready.'
83115
gridState:
84116
type: integer
117+
description: 'Grid connection state. 0: Disconnected, 1: Connected.'
85118
BatVolt:
86119
type: integer
87-
socLimit:
120+
description: 'Battery voltage (0.01 V per unit).'
121+
FMVolt:
88122
type: integer
89-
writeRsp:
123+
description: 'Voltage activation value (V).'
124+
socLimit:
90125
type: integer
91-
acMode:
126+
description: 'SOC limit state. Range: 0-2.'
127+
rssi:
92128
type: integer
93-
inputLimit:
129+
description: 'Wi-Fi signal strength (dBm).'
130+
gridOffPower:
94131
type: integer
95-
outputLimit:
132+
description: 'Off-grid output power (W).'
133+
lampSwitch:
96134
type: integer
97-
socSet:
135+
description: 'Lamp state. 0: Off, 1: On.'
136+
gridOffMode:
98137
type: integer
99-
minSoc:
138+
description: 'Off-grid mode (read-only status; writable via /properties/write).'
139+
IOTState:
100140
type: integer
101-
gridStandard:
141+
description: 'IoT connection state.'
142+
fanSwitch:
102143
type: integer
103-
gridReverse:
144+
description: 'Fan state. 0: Off, 1: On.'
145+
fanSpeed:
104146
type: integer
105-
inverseMaxPower:
147+
description: 'Fan speed level.'
148+
faultLevel:
106149
type: integer
107-
lampSwitch:
150+
description: 'Fault severity level.'
151+
bindstate:
108152
type: integer
109-
IOTState:
153+
description: 'Device bind state.'
154+
VoltWakeup:
110155
type: integer
111-
factoryModeState:
156+
description: 'Voltage wake-up value.'
157+
OldMode:
112158
type: integer
159+
description: 'Legacy operation mode.'
113160
OTAState:
114161
type: integer
162+
description: 'OTA update state.'
115163
LCNState:
116164
type: integer
117-
oldMode:
165+
description: 'LCN connection state.'
166+
factoryModeState:
118167
type: integer
119-
VoltWakeup:
168+
description: 'Factory mode state.'
169+
timestamp:
120170
type: integer
171+
description: 'System timestamp.'
121172
ts:
122173
type: integer
123-
bindstate:
174+
description: 'Unix timestamp.'
175+
timeZone:
124176
type: integer
177+
description: 'Timezone setting.'
125178
tsZone:
126179
type: integer
180+
description: 'Timezone offset.'
127181
chargeMaxLimit:
128182
type: integer
129-
smartMode:
130-
type: integer
131-
rssi:
183+
description: 'Maximum charge power limit (W).'
184+
phaseSwitch:
132185
type: integer
186+
description: 'Phase switch state.'
133187
is_error:
134188
type: integer
189+
description: 'Error flag. 0: No error, 1: Error present.'
190+
acCouplingState:
191+
type: integer
192+
description: 'AC Coupling State (bit field). Bit0: AC-coupled input present (auto-cleared by DSP). Bit1: AC input present flag. Bit2: AC-coupled overload. Bit3: Excess AC input power.'
193+
dryNodeState:
194+
type: integer
195+
description: 'Dry contact status. 1: Connected, 0: Connected (may be reversed depending on actual wiring).'
135196
packData:
136197
type: array
198+
description: 'Battery pack data array. One entry per connected pack.'
137199
items:
138200
type: object
139201
properties:
140202
sn:
141203
type: string
204+
description: 'Battery pack serial number.'
142205
packType:
143206
type: integer
207+
description: 'Pack type (reserved).'
144208
socLevel:
145209
type: integer
210+
description: 'State of charge (%). Range: 0-100.'
146211
state:
147212
type: integer
213+
description: 'Pack state. 0: Standby, 1: Charging, 2: Discharging.'
148214
power:
149215
type: integer
216+
description: 'Battery pack power (W).'
150217
maxTemp:
151218
type: integer
219+
description: 'Max cell temperature stored as 0.1 K. Convert to Celsius: (maxTemp - 2731) / 10.0'
152220
totalVol:
153221
type: integer
222+
description: 'Total pack voltage (V).'
154223
batcur:
155224
type: integer
225+
description: 'Battery current. Raw 16-bit two''s complement. Convert: signed_int16(value) / 10.0 = A'
156226
maxVol:
157227
type: integer
228+
description: 'Max cell voltage (0.01 V per unit).'
158229
minVol:
159230
type: integer
231+
description: 'Min cell voltage (0.01 V per unit).'
160232
softVersion:
161233
type: integer
234+
description: 'Pack firmware version.'
162235
heatState:
163236
type: integer
237+
description: 'Pack heating state. 0: Off, 1: On.'
164238

165239
/properties/write:
166240
post:
@@ -172,17 +246,72 @@ paths:
172246
application/json:
173247
schema:
174248
type: object
249+
required: [sn, properties]
175250
properties:
176251
sn:
177252
type: string
178253
description: Serial number of the device.
179254
properties:
180255
type: object
181-
description: The properties to write to the device.
256+
description: The properties to write to the device. Include only the fields to change.
182257
properties:
183258
acMode:
184259
type: integer
185-
description: AC mode value for the device.
260+
description: 'AC mode. 1: Charge, 2: Discharge.'
261+
minimum: 1
262+
maximum: 2
263+
inputLimit:
264+
type: integer
265+
description: 'AC charge power limit (W).'
266+
outputLimit:
267+
type: integer
268+
description: 'Output power limit (W).'
269+
socSet:
270+
type: integer
271+
description: 'Target state of charge (%). Range: 70-100.'
272+
minimum: 70
273+
maximum: 100
274+
minSoc:
275+
type: integer
276+
description: 'Minimum state of charge (%). Range: 0-50.'
277+
minimum: 0
278+
maximum: 50
279+
gridReverse:
280+
type: integer
281+
description: 'Reverse flow control. Range: 0-2.'
282+
minimum: 0
283+
maximum: 2
284+
inverseMaxPower:
285+
type: integer
286+
description: 'Maximum inverter output power (W).'
287+
gridStandard:
288+
type: integer
289+
description: 'Grid standard. 0: Germany, 1: France, 2: Austria, 3: Switzerland, 4: Netherlands, 5: Spain, 6: Belgium, 7: Greece, 8: Denmark, 9: Italy.'
290+
minimum: 0
291+
maximum: 9
292+
smartMode:
293+
type: integer
294+
description: 'Flash write behaviour. 0: Write to flash. 1: Do not write to flash (device restores previous values after reboot). Recommended for frequent changes.'
295+
minimum: 0
296+
maximum: 1
297+
batCalTime:
298+
type: integer
299+
description: 'Battery calibration time (minutes). Unauthorized modification is not recommended.'
300+
Fanmode:
301+
type: integer
302+
description: 'Fan mode. 0: Fan off, 1: Fan on. Unauthorized modification is not recommended.'
303+
minimum: 0
304+
maximum: 1
305+
Fanspeed:
306+
type: integer
307+
description: 'Fan speed. 0: Auto, 1: 1st gear, 2: 2nd gear. Unauthorized modification is not recommended.'
308+
minimum: 0
309+
maximum: 2
310+
gridOffMode:
311+
type: integer
312+
description: 'Off-grid mode. 0: Standard Mode, 1: Economic Mode, 2: Closure.'
313+
minimum: 0
314+
maximum: 2
186315
responses:
187316
'200':
188317
description: Property successfully written to the device.

0 commit comments

Comments
 (0)