JEMMA DAL APIs functions
This page describes the DAL functions exposed by JEMMA devices. Take a look at DAL Web APIs to find out how to interact with these functions using HTTP REST and WebSocket clients.
Notes about properites: when a property is readable it means the a method get${PropertyName} can be invoked. When it's writable it means that a method set${PropertyName} can be invoked. When it's Eventable it means that you can use OSGi EventAdmin to subscribe to DAL events (they use "org/osgi/service/dal/FunctionEvent/PROPERTY_CHANGED" topic)
Example: if a property named "data" is readable it means that getData method can be invoked. When it's writable it means that setData method can be invoked.
The OnOff function provides functionality to turn On and Off a switch and get its status. OnOff functions uses the "OnOff" suffix in the UID. A function like this is created for every device exposing a ZigBee BooleanControl server.
Example of OnOff function UID:
ZigBee:SmartPlug 1:ah.app.3521399293210526015-8:OnOff
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| data | java.lang.Boolean | the status of the switch | R,E |
| Name | Arguments | Description |
|---|---|---|
| reverse | none | changes the switch status |
| setTrue | none | sets the switch status to true |
| setFalse | none | sets the switch status to false |
##EnergyMeter function
The EnergyMeter function allows to get the current consumption value and the total consumption. It is created for every device exposing a ZigBee SimpleMetering server.
EnergyMeter functions uses the "EnergyMeter" suffix in the UID.
Example of EnergyMeter function UID:
ZigBee:SmartPlug 1:ah.app.3521399293210526015-8:EnergyMeter
the ""dal.meter.flow" service property value can be "in" or "out": it is "in" in case the consumption is measured, false in case the production is measured.
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| current | java.math.BigDecimal | The current consumption | R,E |
| total | java.math.BigDecimal | The total consumption | R,E |
##DoorLock function
The DoorLock function allows to get the current status of a door lock, to open it or close it.It is created for every device exposing a ZigBee DoorLock server. DoorLock functions uses the "DoorLock" suffix in the UID.
Example of DoorLock function UID:
ZigBee:Door Lock 1:ah.app.3781220503199452-1:DoorLock
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| status | java.lang.String | "OPEN" or "CLOSED" | R,E |
###Operations
| Name | Arguments | Description |
|---|---|---|
| open | none | open the door |
| close | none | close the door |
##WindowCovering function
The WindowCovering function allows to get the current status of a window covering, to open it or close it.It is created for every device exposing a ZigBee WindowCovering server. WindowCovering functions uses the "WindowCovering" suffix in the UID.
Example of WindowCovering function UID:
ZigBee:Window Covering 1:ah.app.8987408045443425-1:WindowCovering
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| status | java.lang.Short | a value from 0 (closed) to 255 (opened) | R,E |
###Operations
| Name | Arguments | Description |
|---|---|---|
| openUp | none | open window covering |
| closeDown | none | close the window covering |
##ColorControl function
The ColorLight function allows to get the current HUE and Saturation of a coulored light. It is created for every device exposing a ZigBee ColorControl server. ColorControl functions uses the "ColorControl" suffix in the UID.
Example of WindowCovering function UID:
ZigBee:ColorLight 1:ah.app.36276195726903800-1:ColorControl
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| HS |
|
The current HUE and Saturation on the light bulb | R,W,E |
The HUE value in degrees must be scaled to values from 0 to 254. The Saturation value is the saturation percentage scaled to values from 0 to 254.
Example: If I want to set GREEN as light color, I have to pick up HUE and Saturation values for GREEN.
Green Coulor values:
- HUE: 120°
- Saturation: 100%
The parameters to the setHS be passed are:
[ {"type":"java.lang.Short","value":"85"}, {"type":"java.lang.Short","value":"254"}]
- The HUE have been calculated with the formula: ([HUE in degrees]/360)*254 =~ 85 (for Green)
- The Saturation have been calculated with the formula: ([Saturation %]/100)*254 = 254 (for Green)
##MultiLevelControl function The MultiLevel control function is exposed by every device having a property which can assume a range of values. The MultiLevelControl function uses the suffix "MultiLevelControl" in the UID.
Example of MultiLevelControl function:
ZigBee:ColorLight 1:ah.app.36276195726903800-1:MultiLevelControl
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| data | java.math.BigDecimal | The current level | R,W,E |
In the example above, the MultiLevelControl is used to control the light intensity of a lamp. It accepts values from 0 to 254.
##WashingMachine function
The WashingMachine function allows to get and sets many parameters associated with a Washing Machine. WashingMachine functions uses the "WashingMachine" suffix in the UID.
Example of WashingMachine function:
ZigBee:Washing Machine:ah.app.3521399293213671752-1:WashingMachine
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| temperature | java.lang.Integer | The current temperature for this cycle | R,E |
| cycle | java.lang.Short | The current cycle for this cycle | R,W,E |
| spin | java.lang.Short | The current temperature for this spin | R,W,E |
| RemoteControl | java.lang.Boolean | True if the appliance is remotely controllable | R |
| StartTime | org.energy_home.dal.functions.data.TimeData | The current StartTime for this cycle | R,E |
| FinishTime | org.energy_home.dal.functions.data.TimeData | The current FinishTime for this cycle | R,E |
| RemainingTime | org.energy_home.dal.functions.data.TimeData | The current RemainingTime for this cycle | R,E |
The Washing Machine will accept properties values according to the programmed cycle. The table below summarizes possible values:
| Cycle ID | Cycle description | Temperature values | Spin values |
|---|---|---|---|
| 1 | Cotton Standard | 20,0 | 1600,1200,800,600,400,0 |
| 2 | Synthetics Resistant | 60,40,30,20,0 | 800,600,400,0 |
| 3 | Whites | 60,40,30,20,0 | 1600,1200,800,600,400,0 |
| 4 | Coloureds | 40,30,20,0 | 1600,1200,800,600,400,0 |
| 5 | Darks | 30,20,0 | 800,600,400,0 |
| 6 | Shirts | 40,30,20,0 | 600,400,0 |
| 7 | Duvets | 30,20,0 | 1200,800,600,400,0 |
| 8 | Bed & bath | 60,40,30,20,0 | 1600,1200,800,600,400,0 |
| 9 | Rinse | 0 | 1600,1200,800,600,400,0 |
| 10 | Spin Pump Out | 0 | 1600,1200,800,600,400,0 |
| 11 | Anti Allergy | 60,40,30,20,0 | 1600,1200,800,600,400,0 |
| 12 | Ultradelicates | 30,20,0 | 0 |
| 13 | Wool Platinum Care | 40,30,20,0 | 800,600,400,0 |
| 14 | Mix 30' | 30,20,0 | 800,600,400,0 |
| 15 | Cotton Standard | 60,40,30,20,0 | 1600,1200,800,600,400,0 |
| 16 | Cotton Standard | 40,30,20,0 | 1600,1200,800,600,400,0 |
###Operations
| Name | Arguments | Description |
|---|---|---|
| execStartCycle | none | Starts the cycle now |
| execStopCycle | none | Stops the cycle now |
| execPauseCycle | none | Pauses the cycle now |
| execOverloadPause | none | Pauses the cycle because there is an overload |
| execOverloadPauseResume | none | Resumses the cycle previously stopped because of an overload |
| execOverloadWarning | none | Prints an overload warning on the Washging Machine |
##Fridge function
The Fridge function allows to get and sets many parameters associated with a Fridge. Fridge functions uses the "Fridge" suffix in the UID.
Example of Fridge function UID:
ZigBee:Fridge:ah.app.22732155569492546-1:Fridge
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| FridgeTemperature | java.math.BigDecimal | The current Fridge temperature | R,E |
| FreezerTemperature | java.math.BigDecimal | The current Freezer temperature | R,E |
| EcoMode | java.lang.Boolean | The Eco mode (on/off) | R,W,E |
| HolidayMode | java.lang.Boolean | The Holiday mode (on/off) | R,W,E |
| IceParty | java.lang.Boolean | The IceParty mode (on/off) | R,W,E |
| SuperCoolMode | java.lang.Boolean | The SuperCool mode (on/off) | R,W,E |
| SuperFreezeMode | java.lang.Boolean | The SuperFreeze mode (on/off) | R,W,E |
##Oven function
The Oven function allows to get and sets many parameters associated with an Oven. Oven functions uses the "Oven" suffix in the UID.
Example of Oven function:
ZigBee:Oven:ah.app.3521399293213672714-1:Oven
###Properties
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| temperature | java.math.BigDecimal | The current temperature for this cycle | R,E |
| cycle | java.lang.Short | The current cycle for this cycle | R,E |
| RemoteControl | java.lang.Boolean | True if the appliance is remotely controllable | R |
| StartTime | org.energy_home.dal.functions.data.TimeData | The current StartTime for this cycle | R,E |
| FinishTime | org.energy_home.dal.functions.data.TimeData | The current FinishTime for this cycle | R,E |
| RemainingTime | org.energy_home.dal.functions.data.TimeData | The current RemainingTime for this cycle | R,E |
The Oven will accept properties values according to the programmed cycle. The table below summarizes possible values:
| Cycle ID | Cycle description | Temperature values |
|---|---|---|
| 1 | Multilevel | 30,250 |
| 2 | Grill | 30,270 |
| 3 | Fan Grilling | 30,250 |
| 4 | Roast | 30,250 |
| 5 | Fish | 30,250 |
| 6 | Pizza | 30,250 |
| 7 | Proving | 35,40 |
| 8 | Pastry | 30,250 |
| 9 | Pasteurisation | 120,125 |
| 10 | Slow cook meat | 80,85 |
| 11 | Slow cook fish | 70,75 |
| 12 | Slow cook vegetables | 105,110 |
| 13 | Defrosting | 30,35 |
| 14 | Eco cooking | 30,200 |
| 15 | Bread | pre-defined |
| 16 | Beef | pre-defined |
| 17 | Veal | pre-defined |
| 18 | Lamb | pre-defined |
| 19 | Pork | pre-defined |
| 20 | Chicken | pre-defined |
| 21 | Fish fillet | pre-defined |
| 22 | Fish en Papillote | pre-defined |
| 23 | Tarts | pre-defined |
| 24 | Shortcrust tarts | pre-defined |
| 25 | Brioche | pre-defined |
| 26 | Cake | pre-defined |
| 27 | Desserts | pre-defined |
| 28 | Paella | pre-defined |
| 29 | Pilau rice | pre-defined |
| 30 | Yoghurt | pre-defined |
| 31 | Pizza with stone | pre-defined |
###Operations
| Name | Arguments | Description |
|---|---|---|
| execStartCycle | none | Starts the cycle now |
| execStopCycle | none | Stops the cycle now |
| execOverloadPause | none | Pauses the cycle because there is an overload |
| execOverloadPauseResume | none | Resumses the cycle previously stopped because of an overload |
| execOverloadWarning | none | Prints an overload warning on the Washging Machine |
You can execute Start/Stop operations only against cycle with pre-defined value for safety/normative reasons
##PowerProfile function The PowerProfile function allows to get parameters associated with the scheduled energy consumption of appliances. PowerProfile functions uses the "PowerProfile" suffix in the UID.
| Name | Type | Description | Readable(R)/Writable(W)/Eventable(E) |
|---|---|---|---|
| TotalProfileNum | java.lang.Short | Total number of power profile available | R |
| PowerProfilePhases | org.energy_home.dal.functions.data.PowerProfilePhasesData | The energy phases | R |
NOTE: to see power profile, first you need to invoke getTotalProfileNum, the getPowerProfilePhases specifying as an argument a Short value referring to the power profile you want to get info about.
For instance if getTotalProfileNum returns "1", it means that there is only 1 PowerProfile and you have to specify the Short argument "0" when you invoke getPowerProfilePhases (like array indexing).
An example response of getPowerProfilePhases request is
{"powerProfileID":1,"totalProfileNum":1,"phases":[{"Energy":0,"EnergyPhaseID":1,"ExpectedDuration":0,"MacroPhaseID":0,"MaxActivationDelay":65535},{"Energy":257,"EnergyPhaseID":0,"ExpectedDuration":19984,"MacroPhaseID":0,"MaxActivationDelay":25},{"Energy":0,"EnergyPhaseID":0,"ExpectedDuration":0,"MacroPhaseID":0,"MaxActivationDelay":0}]