RPC Method Reference

List of Functions

CategoryMethodDescription
XML-RPCsystem.getCapabilitiesLists Homegear's RPC capabilities
XML-RPCsystem.listMethodsLists all supported RPC methods
XML-RPCsystem.methodHelpReturns the short description of an RPC method
XML-RPCsystem.methodSignatureReturns an RPC method's signature
XML-RPCsystem.multicallUse this method to call multiple RPC methods at once in order to reduce traffic.
GeneralgetInstanceIdReturns the unique Homegear instance ID
GeneralgetServiceMessagesReturns all service messages
GeneralgetVersionReturns Homegear's version number
GenerallogLevelGets or sets the current log level
GeneralrunScriptExecutes a script located in Homegear's script directory
GeneralsetLanguageSets the language of the connection.
GeneralwriteLogWrites a message to the Homegear log
DatabasedeleteDataDeletes previously stored data from Homegear's key-value database
DatabasegetDataRetrieves previously stored data from Homegear's key-value database
DatabasesetDataStores data in Homegear's key-value database
DevicesactivateLinkParamsetSimulates a remote key press
DevicesaddLinkCreates a direct link between two devices
DevicescopyConfigCopies configuration parameters from one channel to another
DevicesdeleteDeviceUnpairs a peer or resets it to factory defaults
DevicesgetAllConfigReturns all peer configuration parameters and some additional metadata
DevicesgetAllValuesReturns all peer configuration parameters and some additional metadata
DevicesgetDeviceDescriptionReturns static information about a device
DevicesgetDeviceInfoReturns dynamic information about a device
DevicesgetLinkInfoReturns name and description of a direct device link
DevicesgetLinkPeersReturns all peers and channels a channel is linked to
DevicesgetLinksReturns direct links of all or a single peer
DevicesgetNameReturns the name of a peer
DevicesgetParamsetReturns a peer's configuration parameters
DevicesgetParamsetDescriptionReturns information about a peer's parameter set
DevicesgetParamsetIdReturns the ID of a parameter set
DevicesgetPeerIdReturns all peers matching a filter condition
DevicesgetValueReturns the value of a device variable
DeviceslistDevicesLists information about all existing peers
DeviceslistTeamsLists information about all existing teams
DevicesputParamsetSets device configuration parameters
DevicesremoveLinkRemoves a direct link between two devices
DevicessetIdChanges the ID of a peer
DevicessetNameSets the name of a peer
DevicessetTeamAdds a device to or removes it from a team
DevicessetValueSets the value of a device variable
EventsabortEventResetAborts an event's reset timer
EventsaddEventCreates an event to Homegear's event engine
EventsenableEventEnables or disables an event
EventsgetEventReturns EventDescription for a single event
EventslistEventsReturns all events
EventsremoveEventRemoves an event
EventstriggerEventManually triggers an event
Event ServerclientServerInitializedChecks if an RPC client's RPC server was successfully registered and if it still is registered
Event ServerinitRegisters a client's RPC server with Homegear to receive events
Event ServerlistClientServersReturns information about all RPC servers registered with Homegear by clients
Event ServersubscribePeersSubscribes peer events that are to be sent to an event server when the init flag "subscribePeers" is used
Event ServertriggerRpcEventManually sends an RPC event to all RPC event servers
Event ServerunsubscribePeersUnsubscribes peer events after subscribing them with subscribePeers
FamilieslistFamiliesReturns information about all device families (ID, name, pairing methods)
Firmware UpdatesgetUpdateStatusReturns firmware update status information
Firmware UpdatesupdateFirmwareUpdates the firmware of a device
InfluxDBinfluxdbCreateContinuousQueryCreates a continuous query for number measurements with Homegear's default settings to store aggregated data in the low resolution table
InfluxDBinfluxdbGetDatabaseReturns the name of the InfluxDB database used by Homegear
InfluxDBinfluxdbGetLoggedVariablesReturns all variables logged by Homegear InfluxDB
InfluxDBinfluxdbQueryExecutes an InfluxDB query
InfluxDBinfluxdbSetLoggingEnables automatic logging of values for a specific variable in InfluxDB
InfluxDBinfluxdbWriteExecutes an InfluxDB write
MetadatadeleteMetadataDeletes previously stored metadata
MetadatagetAllMetadataReturns all the metadata of one peer
MetadatagetMetadataRetrieves previously stored metadata
MetadatasetMetadataStores metadata for a peer
Node-BLUEgetNodeVariableExecutes "getNodeVariable" in the specified node.
Node-BLUEsetNodeVariableExecutes "setNodeVariable" in the specified node.
PairingaddDevicePairs a device without enabling pairing mode
PairingcreateDeviceManually creates a device
PairinggetInstallModeReturns the time left in pairing mode
PairinggetPairingInfoReturns information about communication modules and how devices of a family are paired
PairingsearchDevicesStarts a device search for all supported device families
PairingsetInstallModeEnables pairing mode
Physical InterfaceslistBidcosInterfacesThis method exists only for compatibility reasons.
Physical InterfaceslistInterfacesLists all physical interfaces with status information
Physical InterfacessetInterfaceSets the physical interface Homegear uses to communicate with a peer
RolesaddRoleToVariableAdds a role to a variable
RolesaggregateRolesAggregates values of variables with specific roles
RolescreateRoleCreates a new role
RolesdeleteRoleDeletes a role
RolesgetRoleMetadataReturns the metadata of an existing role
RolesgetRolesReturns information about all roles
RolesgetVariablesInRoleReturns all variables of a role
RolesremoveRoleFromVariableRemoves a role from a variable
RolessetRoleMetadataSets the metadata of an existing role
RolesupdateRoleUpdates the translations and metadata of an existing role
Rooms and CategoriesaddBuildingPartToBuildingAssigns a building part to a building
Rooms and CategoriesaddCategoryToChannelAdds a category to a channel
Rooms and CategoriesaddCategoryToDeviceAdds a category to a device
Rooms and CategoriesaddCategoryToSystemVariableAdds a category to a system variable
Rooms and CategoriesaddCategoryToVariableAdds a category to a variable
Rooms and CategoriesaddChannelToRoomAssigns a channel to a room
Rooms and CategoriesaddDeviceToRoomAssigns a device to a room
Rooms and CategoriesaddRoomToStoryAssigns a room to a story
Rooms and CategoriesaddStoryToBuildingAssigns a story to a building
Rooms and CategoriesaddSystemVariableToRoomAssigns a system variable to a room
Rooms and CategoriesaddVariableToRoomAssigns a variable to a room
Rooms and CategoriescreateBuildingCreates a new building
Rooms and CategoriescreateBuildingPartCreates a new building part
Rooms and CategoriescreateCategoryCreates a new category
Rooms and CategoriescreateRoomCreates a new room
Rooms and CategoriescreateStoryCreates a new story
Rooms and CategoriesdeleteBuildingDeletes a building
Rooms and CategoriesdeleteBuildingPartDeletes a building part
Rooms and CategoriesdeleteCategoryDeletes a category
Rooms and CategoriesdeleteRoomDeletes a room
Rooms and CategoriesdeleteStoryDeletes a story
Rooms and CategoriesgetBuildingMetadataReturns the metadata of an existing building
Rooms and CategoriesgetBuildingPartMetadataReturns the metadata of an existing building part
Rooms and CategoriesgetBuildingPartsReturns information about all building parts
Rooms and CategoriesgetBuildingPartsInBuildingReturns all building parts of a building
Rooms and CategoriesgetBuildingsReturns information about all buildings
Rooms and CategoriesgetCategoriesReturns information about all categories
Rooms and CategoriesgetCategoryMetadataReturns the metadata of an existing category
Rooms and CategoriesgetChannelsInCategoryReturns all channels of a category
Rooms and CategoriesgetChannelsInRoomReturns all channels of a room
Rooms and CategoriesgetDevicesInCategoryReturns all devices of a category
Rooms and CategoriesgetDevicesInRoomReturns all devices of a room
Rooms and CategoriesgetRoomMetadataReturns the metadata of an existing room
Rooms and CategoriesgetRoomsReturns information about all rooms
Rooms and CategoriesgetRoomsInStoryReturns all rooms of a story
Rooms and CategoriesgetStoriesReturns information about all stories
Rooms and CategoriesgetStoriesInBuildingReturns all stories of a building
Rooms and CategoriesgetStoryMetadataReturns the metadata of an existing story
Rooms and CategoriesgetSystemVariablesInCategoryReturns all system variables of a category
Rooms and CategoriesgetSystemVariablesInRoomReturns all system variables of a room
Rooms and CategoriesgetVariablesInCategoryReturns all variables of a category
Rooms and CategoriesgetVariablesInRoomReturns all variables of a room
Rooms and CategoriesremoveBuildingPartFromBuildingRemoves a building part from a building
Rooms and CategoriesremoveCategoryFromChannelRemoves a category from a channel
Rooms and CategoriesremoveCategoryFromDeviceRemoves a category from a device
Rooms and CategoriesremoveCategoryFromSystemVariableRemoves a category from a system variable
Rooms and CategoriesremoveCategoryFromVariableRemoves a category from a variable
Rooms and CategoriesremoveChannelFromRoomRemoves a channel from a room
Rooms and CategoriesremoveDeviceFromRoomRemoves a device from a room
Rooms and CategoriesremoveRoomFromStoryRemoves a room from a story
Rooms and CategoriesremoveStoryFromBuildingRemoves a story from a building
Rooms and CategoriesremoveSystemVariableFromRoomRemoves a system variable from a room
Rooms and CategoriesremoveVariableFromRoomRemoves a variable from a room
Rooms and CategoriessetBuildingMetadataSets the metadata of an existing building
Rooms and CategoriessetBuildingPartMetadataSets the metadata of an existing building part
Rooms and CategoriessetCategoryMetadataSets the metadata of an existing category
Rooms and CategoriessetRoomMetadataSets the metadata of an existing room
Rooms and CategoriessetStoryMetadataSets the metadata of an existing story
Rooms and CategoriesupdateBuildingUpdates the translations and metadata of an existing building
Rooms and CategoriesupdateBuildingPartUpdates the translations and metadata of an existing building part
Rooms and CategoriesupdateCategoryUpdates the translations and metadata of an existing category
Rooms and CategoriesupdateRoomUpdates the translations and metadata of an existing room
Rooms and CategoriesupdateStoryUpdates the translations and metadata of an existing story
System VariablesdeleteSystemVariableDeletes a system variable
System VariablesgetAllSystemVariablesReturns all system variables
System VariablesgetSystemVariableGets the value of a system variable
System VariablesgetSystemVariableFlagsReturns the flags assigned to a system variable
System VariablessetSystemVariableCreates or updates a system variable
UIaddUiElementAdds an UI element to Homegear's UI
UIcheckUiElementSimpleCreationChecks if automatic UI element creation is possible on a variable
UIcreateUiNotificationCreates a new UI notification
UIgetAllUiElementsReturns all UI elements
UIgetAvailableUiElementsReturns UI elements that can be added
UIgetCategoryUiElementsReturns all UI elements assigned to a category
UIgetRoomUiElementsReturns all UI elements assigned to a room
UIgetUiElementMetadataGets metadata of an UI element
UIgetUiNotificationReturns a single UI notification
UIgetUiNotificationsReturns all UI notifications
UIremoveUiElementSets metadata of an UI element
UIremoveUiNotificationRemoves an UI notification
UIrequestUiRefreshRequests the UI to be reloaded
UIsetUiElementMetadataSets metadata of an UI element
UIuiNotificationActionTrigger a UI notification button action
Variable ProfilesactivateVariableProfileActivates a variable profile (= "scene")
Variable ProfilesaddVariableProfileAdds an UI element to Homegear's UI (= "scene")
Variable ProfilesdeleteVariableProfileDeletes a variable profile (= "scene")
Variable ProfilesgetAllVariableProfilesReturns all variable profiles (= "scenes")
Variable ProfilesgetVariableProfileReturns a single variable profile (= "scene")
Variable ProfilesupdateVariableProfileUpdates an existing variable profile (= "scene")

List of Event Server Functions

A client can implement an event server to receive events from Homegear. To register an event server with Homegear, call init() (not necessary for WebSockets, MQTT or Unix Domain Sockets).
  • For JSON-RPC, XML-RPC and Binary RPC Homegear checks which methods are implemented by calling system.listMethods(). That means not all methods need to be implemented.
  • The method event() is always wrapped in system.multicall even when only one event is broadcast. The reason for this is that some clients do not support event() without it.
CategoryMethodDescription
Event Server - DeviceseventCalled on variable changes
Event Server - GeneralerrorCalled when an error occurs in Homegear
Event Server - UIrequestUiRefreshRequests the UI to be reloaded
Event Server - UIuiNotificationActionCalled when a UI notification button is pressed
Event Server - UIuiNotificationCreatedCalled when there is a new UI notification
Event Server - UIuiNotificationRemovedCalled when a new UI notification has been removed
Event Server - Variable ProfilesvariableProfileStateChangedCalled when a variable profile changes it's state
 

Overview

General

Homegear supports different communication protocols:

  • XML-RPC: Easy to use and implemented in most programming languages.
  • Binary-RPC: Fast en- and decoding
  • JSON-RPC: Also easy to use.
  • WebSockets: For communication between Homegear and web browser (see HomegearWS)
  • MQTT: Popular protocol specialized for the Internet of Things.
  • IPC / Unix Domain Sockets: For communication between Homegear and other programs running on the same system.

Each supported protocol supports all RPC methods in this reference. Additionally all RPC methods can be called in Homegear's script engine.

The RPC methods are based on and compatible to the methods defined in the specification of the HomeMatic XML-RPC Interface. For more information and for implementation examples see the Homegear Documentation.

 

XML-RPC Types

These types defined by the XML-RPC Specification are supported by Homegear:

Tag Type Example / Notes
<i4> or <int> Four-byte signed integer -12
<i8> Eight-byte signed integer 55247185375
<boolean> 0 (false) or 1 (true) 1
<string> String. > and & need to be escaped. Hello world &gt; &amp;
<double> Double-precision signed floating point number -12.214
<base64> base64-encoded binary data eW91IGNhbid0IHJlYWQgdGhpcyE=
<struct> Associative array
<struct>
  <member>
    <name>lowerBound</name>
    <value><i4>18</i4></value>
  </member>
  <member>
    <name>upperBound</name>
    <value><i4>139</i4></value>
  </member>
</struct>
<array> Non-associative array
<array>
  <data>
    <value><i4>12</i4></value>
    <value><string>Egypt</string></value>
    <value><boolean>0</boolean></value>
    <value><i4>-31</i4></value>
  </data>
</array>
<nil> or <ex:nil> Void Homegear accepts or but does not send them!
 

Homegear-specific Types

In addition to the basic types, Homegear defines the following structures:

DeviceDescription

The struct DeviceDescription describes one HomeMatic device. One HomeMatic device has multiple device descriptions:

  • One for the parent device
  • and one for each channel (0, 1, ...)

Enumerations used in DeviceDescription

Name Values Description
Flags 1 Visible: Device should be visible to the user
2 Internal: Device is only used internally
8 Dontdelete: Device can't (or shouldn't) be deleted
Direction 0 DIRECTION_NONE (no links are supported)
1 DIRECTION_SENDER
2 DIRECTION_RECEIVER
RXMode 1 RX_ALWAYS: Device is always in RX mode
2 RX_BURST: Device is in "wake on radio" mode and can be woken up with "wake on radio" packets
4 RX_CONFIG: Device can be reached by enabling the pairing mode
8 RX_WAKEUP: Device sends cyclic "wake me up" packets and is only reachable every 2 to 3 minutes
16 RX_LAZY_CONFIG: Device accepts config packets after normal packets (e. g. a packet from a remote)

Members

DeviceDescription of Parent Device
Name Type Description
FAMILY Integer The ID of the family the device belongs to (e. g. 0 for HomeMatic BidCoS, 1 for HomeMatic Wired, 2 for Insteon, ...)
TYPE String Type of the device
TYPE_ID Integer The type ID of the device
DESCRIPTION String A short description of the device
LONG_DESCRIPTION String A description of the device
ID Integer The id of the device (e. g. 131)
ADDRESS String Serialnumber of the device (e. g. JEQ0123456)
CHILDREN Array<String> For compatibility. Addresses of the channels (e. g. JEQ0123456:1)
CHANNELS Array<Integer> Indexes of all available channels
PARENT String Empty for parent device
PARAMSETS Array<String> Names of the available parameter sets (MASTER, VALUES and/or LINK)
FIRMWARE String Optional. Firmware version (e. g. "2.1"). "?" for teams.
AVAILABLE_FIRMWARE String Optional. Firmware version available for update (e. g. "2.2"). Only set when a newer firmware version is available.
VERSION Integer Version of the XML file
FLAGS Flags or-linked flags for the GUI
RF_ADDRESS Integer For compatability. Physical address of the device.
PHYSICAL_ADDRESS Integer Physical address of the device
RX_MODE RXMode The supported RX modes of the device.
INTERFACE String Only for compatibility. Serial number of the central.
ROOM Integer The ID of the room assigned to this device. Only returned if set and if specified in parameter fields.
CATEGORIES Array<Integer> The IDs of the categories assigned to this device. Only returned if at least one category is set and if specified in parameter fields.
DeviceDescription of Channel
Name Type Description
TYPE String Type of the channel
FAMILY Integer The ID of the family the device belongs to (e. g. 0 for HomeMatic BidCoS, 1 for HomeMatic Wired, 2 for Insteon, ...)
ID Integer The id of the device (e. g. 131)
CHANNEL Integer The channel number (e. g. 2)
ADDRESS String Serialnumber and index of the channel (e. g. JEQ0123456:1)
PARENT String Serialnumber of parent device (e. g. JEQ0123456)
PARENT_TYPE String Type of the parent device
INDEX Integer Channel number
AES_ACTIVE Integer "1" when AES handshakes are enabled for the channel otherwise "0". This variable is of type Integer for compatibility.
PARAMSETS Array<String> Names of the available parameter sets (MASTER, VALUES and/or LINK)
VERSION Integer Version of the XML file
FLAGS Flags or-linked flags for the GUI
LINK_SOURCE_ROLES String Source roles defined for this channel in the XML file seperated by space
LINK_TARGET_ROLES String Target roles defined for this channel in the XML file seperated by space
DIRECTION Direction Direction of the channel (sender or receiver)
GROUP String Optional. Only when device has grouped channels. Serial number and index of the grouped channel (e. g. JEQ0123456:3)
TEAM String Optional. Only when channel supports teams. Serial number of the team (e. g. *JEQ0123456 - note the "*")
TEAM_TAG String Optional. Only when channel supports teams or for teams. Type of the team ("team_tag" attribute of the team's XML file).
TEAM_CHANNELS Array<String> Optional. Only for teams. Array of peers (serialnumber and channel) paired to this team (e. g. JEQ0234567:1)
ROOM Integer The ID of the room assigned to this channel. Only returned if set and if specified in parameter fields.
CATEGORIES Array<Integer> The IDs of the categories assigned to this channel. Only returned if at least one category is set and if specified in parameter fields.

Examples

HM-CC-TC - Parent Device
(Struct length=10)
{
  [FAMILY]
  {
    (Integer) 0
  }
  [ID]
  {
    (Integer) 37
  }
  [ADDRESS]
  {
    (String) JEQ0550760
  }
  [CHILDREN]
  {
    (Array length=4)
    {
      (String) JEQ0550760:0
      (String) JEQ0550760:1
      (String) JEQ0550760:2
      (String) JEQ0550760:3
    }
  }
  [CHANNELS]
  {
    (Array length=4)
    {
      (Integer) 0
      (Integer) 1
      (Integer) 2
      (Integer) 3
    }
  }
  [FIRMWARE]
  {
    (String) 2.1
  }
  [FLAGS]
  {
    (Integer) 1
  }
  [PARAMSETS]
  {
    (Array length=1)
    {
      (String) MASTER
    }
  }
  [PARENT]
  {
    (String)
  }
  [RF_ADDRESS]
  {
    (String) 1936689
  }
  [TYPE]
  {
    (String) HM-CC-TC
  }
  [VERSION]
  {
    (Integer) 14
  }
}
HM-CC-TC - Channel 1
(Struct length=12)
{
  [FAMILY]
  {
    (Integer) 0
  }
  [ID]
  {
    (Integer) 37
  }
  [CHANNEL]
  {
    (Integer) 1
  }
  [ADDRESS]
  {
    (String) JEQ0550760:1
  }
  [AES_ACTIVE]
  {
    (Integer) 0
  }
  [DIRECTION]
  {
    (Integer) 1
  }
  [FLAGS]
  {
    (Integer) 1
  }
  [INDEX]
  {
    (Integer) 1
  }
  [LINK_SOURCE_ROLES]
  {
    (String) WEATHER_TH
  }
  [LINK_TARGET_ROLES]
  {
    (String)
  }
  [PARAMSETS]
  {
    (Array length=3)
    {
      (String) MASTER
      (String) VALUES
      (String) LINK
    }
  }
  [PARENT]
  {
    (String) JEQ0550760
  }
  [PARENT_TYPE]
  {
    (String) HM-CC-TC
  }
  [TYPE]
  {
    (String) WEATHER
  }
  [VERSION]
  {
    (Integer) 14
  }
}
 

DynamicResetTime

The struct DynamicResetTime defines how many seconds to wait before executing the reset method after an event was raised (in short: the "reset time"). This is useful for example when you want to increase the time light stays switched on with each motion detector event.

Enumerations Used in DynamicResetTime

Name Values Description
Operation 1 Addition
2 Subtraction
3 Multiplication
4 Division

Members

Name Type Description
INITIALTIME Integer The initial reset time in seconds.
RESETAFTER Integer The time in seconds to wait before the reset time is reset to "INITIALTIME".
OPERATION Operation The mathematical operation to use on the current value of reset time.
FACTOR Float The factor to apply to the current reset time with the operation defined in "OPERATION".
LIMIT Integer The upper (addition, multiplication) or lower (subtraction, division) limit of the reset time (in seconds).
CURRENTTIME Integer Not writeable. Shows the current reset time in seconds when listing events.

Example: When "INITIALTIME" is 30, "FACTOR" is 2.0 and OPERATION is "Multiplication" then with the first event the reset time is 30, with the second 60, with the third 120 and so on until no event occurs for the time defined with "RESETAFTER".

When "LIMIT" is defined, the reset time will be capped at that limit. Let's say for the example above "LIMIT" is 300. Then the fourth event will increase the reset time to 240. The fifth event would increase the reset time to 480 which is greater than "LIMIT" so the reset time is set to 300.

Example

(Struct length=5)
{
  [INITIALTIME]
  {
    (Integer) 30
  }
  [RESETAFTER]
  {
    (Integer) 300
  }
  [OPERATION]
  {
    (Integer) 3
  }
  [FACTOR]
  {
    (Float) 2.0
  }
  [LIMIT]
  {
    (Integer) 300
  }
}
 

EventDescription

The struct EventDescription defines either a triggered or timed Homegear event.

  • Triggered events are checked when Homegear receives a packet from a device. They are raised e. g. when a device's parameter is changed.
  • Timed events can be triggered at a certain time point or recurrently (e. g. every two minutes).

Enumerations Used in EventDescription

Name Values Description
Type 0 Triggered
1 Timed
Trigger 1 Unchanged: The parameter is unchanged compared to the previous value.
2 Changed: The parameter has changed compared to the previous value.
3 Greater: The parameter is now greater than the previous value.
4 Less: The parameter is now smaller than the previous value.
5 GreaterOrUnchanged: The parameter is now greater than the previous value or unchanged.
6 LessOrUnchanged: The parameter is now smaller than the previous value or unchanged.
7 Updated: The parameter was updated. This trigger is always true when a packet with the specified parameter is received. You have to use this trigger for parameters of type "Action".
8 Value: The parameter value equals "TRIGGERVALUE".
9 NotValue: The parameter does not equal "TRIGGERVALUE".
10 GreaterThanValue: The parameter is greater than "TRIGGERVALUE".
11 LessThanValue: The parameter is smaller than "TRIGGERVALUE".
12 GreaterOrEqualValue: The parameter is greater than or equal "TRIGGERVALUE".
13 LessOrEqualValue: The parameter is less than or equal "TRIGGERVALUE"

Members

EventDescription for Triggered Event
Name Type Description
TYPE Type (Integer) Type of the event ("timed" or "triggered")
ID String Arbitrary ID to identify the event
ENABLED Boolean Defines whether the event is enabled.
REPLACE Boolean If true an existing event with the same ID is replaced without RPC error.
PEERID Integer ID of the peer for which the event should be executed (e. g. 131). To create an event for system variable changes, leave it out or set it to "0", for metadata variable changes it needs to be set.
PEERCHANNEL Integer Optional. CHANNEL of the peer for which the event should be executed (e. g. 1). To create an event for system variable or metadata variable changes, leave it out or set it to "-1".
VARIABLE String The name of the device's variable to check (e. g. "STATE")
TRIGGER Trigger (Integer) Which trigger to use
TRIGGERVALUE Variant Only needed for triggers 8 to 13. The value to compare the parameter value to.
EVENTMETHOD String The name of the XML-RPC method to execute when event is raised.
EVENTMETHODPARAMS Array<Variant> The parameters to pass to "EVENTMETHOD".
RESETAFTER Integer or DynamicResetTime Optional. Time in seconds after which "RESETMETHOD" will be executed.
RESETMETHOD String Optional. Mandatory when "RESETAFTER" is specified. The XML-RPC method to execute after waiting the amount of seconds defined with "RESETAFTER".
RESETMETHODPARAMS Array<Variant> The parameters to pass to "RESETMETHOD".
LASTVALUE Variant Not writeable. The last value of "VARIABLE" received by the event handler.
LASTRAISED Integer Not writeable. Unix time stamp of the last time the event was raised.
LASTRESET Integer Not writeable. Unix time stamp of the last time the event was reset.
EventDescription for Timed Event
Name Type Description
TYPE Type Type of the event ("timed" or "triggered")
ID String Arbitrary ID to identify the event
ENABLED Boolean Defines whether the event is enabled.
REPLACE Boolean If true an existing event with the same ID is replaced without RPC error.
EVENTTIME Integer The unix timestamp of either a time point at which to execute a single event. Or the start time point of a recurrent event. Will be set to the current time when undefined or 0.
RECUREVERY Integer Optional. The time in seconds after which to recur the event (e. g. 120 (= 2 minutes) or 604800 (= 1 week).
ENDTIME Integer Optional. The time point when a recurrent event should be deleted.
EVENTMETHOD String The name of the XML-RPC method to execute when event is raised.
EVENTMETHODPARAMS Array<Variant> The parameters to pass to "EVENTMETHOD".

Examples

Example 1 - Triggered Event with Dynamic Reset Time
(Struct length=11)
{
  [TYPE]
  {
    (Integer) 0
  }
  [ID]
  {
    (String) MyThirdCustomEvent
  }
  [PEERID]
  {
    (Integer) 32
  }
  [PEERCHANNEL]
  {
    (Integer) 1
  }
  [VARIABLE]
  {
    (String) MOTION
  }
  [TRIGGER]
  {
    (Integer) 8
  }
  [TRIGGERVALUE]
  {
    (Boolean) 1
  }
  [EVENTMETHOD]
  {
    (String) setValue
  }
  [EVENTMETHODPARAMS]
  {
    (Array length=3)
    {
      (Integer) 12
      (Integer) 1
      (String) STATE
      (Boolean) 1
    }
  }
  [RESETAFTER]
  {
    (Struct length=5)
    {
      [INITIALTIME]
      {
        (Integer) 30
      }
      [RESETAFTER]
      {
        (Integer) 300
      }
      [OPERATION]
      {
        (Integer) 3
      }
      [FACTOR]
      {
        (Float) 2.0
      }
      [LIMIT]
      {
        (Integer) 300
      }
    }
  }
  [RESETMETHOD]
  {
    (String) setValue
  }
  [RESETMETHODPARAMS]
  {
    (Array length=3)
    {
      (Integer) 12
      (Integer) 1
      (String) STATE
      (Boolean) 0
    }
  }
}
Example 2 - Timed Event (Recurrent with End Time)
(Struct length=7)
{
  [TYPE]
  {
    (Integer) 1
  }
  [ID]
  {
    (String) MyFifthCustomEvent
  }
  [EVENTTIME]
  {
    (Integer) 1379941325
  }
  [RECUREVERY]
  {
    (Integer) 120
  }
  [ENDTIME]
  {
    (Integer) 1380027725
  }
  [EVENTMETHOD]
  {
    (String) runScript
  }
  [EVENTMETHODPARAMS]
  {
    (Array length=3)
    {
      (String) myScript.sh
      (Boolean) 0
    }
  }
}
 

InterfaceDescription

The struct InterfaceDescription describes a physical interface used by Homegear.

Members

Name Type Description
FAMILYID Integer The id of the device family the physical device communicates with.
ID String Unique identifier for this interface.
SERIALNUMBER String The serial number of the interface.
FIRMWAREVERSION String The firmware version of the interface.
CONNECTED Boolean State of the device. When "false" device is not working.
DEFAULT Boolean "True" when this interface is the default interface for this device family.
LASTPACKETRECEIVED Integer Unix time stamp of the last received packet.
LASTPACKETSENT Integer Unix time stamp of the last sent packet.
PHYSICALADDRESS Integer The physical address of the device.
TYPE String The type of the physical device.

Example

(Array length=2)
{
  (Struct length=7)
  {
    [ID]
    {
      (String) MyInterface
    }
    [CONNECTED]
    {
      (Boolean) 1
    }
    [DEFAULT]
    {
      (Boolean) 1
    }
    [FAMILYID]
    {
      (Integer) 0
    }
    [LASTPACKETRECEIVED]
    {
      (Integer) 1393069264
    }
    [LASTPACKETSENT]
    {
      (Integer) 1393069364
    }
    [PHYSICALADDRESS]
    {
      (Integer) 16581789
    }
    [TYPE]
    {
      (String) cc1100
    }
  }
  (Struct length=7)
  {
    [ID]
    {
      (String) MySecondInterface
    }
    [CONNECTED]
    {
      (Boolean) 1
    }
    [DEFAULT]
    {
      (Boolean) 1
    }
    [FAMILYID]
    {
      (Integer) 1
    }
    [LASTPACKETRECEIVED]
    {
      (Integer) 1393069243
    }
    [LASTPACKETSENT]
    {
      (Integer) 1393069243
    }
    [PHYSICALADDRESS]
    {
      (Integer) 1
    }
    [TYPE]
    {
      (String) rs485
    }
  }
}
 

LinkDescription

The struct LinkDescription describes a direct link between the channels of two devices (e. g. peer 12 channel 1 and peer 25 channel 3).

Special Types used in LinkDescription

Name Values Description
LinkFlags 1 Sender does not know receiver or is unknown
2 Receiver does not know sender or is unknown
4 Sender and receiver are two different channels of the same device. Used only when one of the channels is "virtual" and in combination with one of the broken flags.

Members

Name Type Description
SENDER_ID Integer The id of the sending device
SENDER_CHANNEL Integer The channel of the sending device
SENDER String For compatibility. The serial number and channel of the sending device separated by colon
RECEIVER_ID Integer The id of the receiving device
RECEIVER_CHANNEL Integer The channel of the receiving device
RECEIVER String For compatibility. The serial number and channel of the receiving device separated by colon
FLAGS LinkFlags or-linked LinkFlags
NAME String The name of the link as defined in addLink or setLinkInfo
SENDER_PARAMSET Paramset Optional (see getLinks). The link parameter set of the sending device.
RECEIVER_PARAMSET Paramset Optional (see getLinks). The link parameter set of the receiving device.
SENDER_DESCRIPTION DeviceDescription Optional (see getLinks). The device description of the sending channel.
RECEIVER_DESCRIPTION DeviceDescription Optional (see getLinks). The device description of the receiving channel.
 

ParameterDescription

The struct ParameterDescription describes one parameter of a parameter set.

Enumerations used in ParameterDescription

Name Values Description
Operations 1 Read
2 Write
4 Event (deprecated)
Flags 1 Visible: Parameter should be visible to the user
2 Internal: Parameter is only used internally
4 Transform: Changes to this parameter completely change the behavior of a channel. Changes are only allowed when the channel is not linked.
8 Service: This parameter should be processed as service message. Only Boolean and Integer are allowed. 0 or false means there is no message.
16 Sticky: Only for service messages. A sticky service message has to be manually reset by the user.

Structs used in ParameterDescription

Name Description Fields Field Description
Special Defines values with a special meaning outside the value range ID Name of the special value
VALUE The special value

Members

These are the possible values for TYPE.

Name Type Description
TYPE String Data type of the parameter
OPERATIONS Operations or-linked operations (Read: 1, Write: 2, Event: 3)
FLAGS Flags or-linked flags for the GUI
DEFAULT Same as parameter Default value
MAX Same as parameter Largest possible value
MIN Same as parameter Smallest possible value
UNIT String Unit of measurement
TAB_ORDER Integer Position of the parameter inside the parameter set
CONTROL String Optional. Tells the GUI which control to use for this parameter.
SPECIAL Array of type Special Only for types FLOAT and INTEGER. Defines special values outside the value range.
VALUE_LIST Array of type String Only for type ENUM. Defines names for the enumeration. The array index of the name is the associated value. If an array element is empty, the value is not defined.
LABEL String Optional. The human readable name of the parameter (e. g. "Setpoint temperature").
DESCRIPTION String Optional. A short description of the parameter (e. g. "Gets or sets the current setpoint temperature.")
FORM_FIELD_TYPE String Optional. The form field type to use in forms.
FORM_POSITION Integer Optional. The position of the parameter to use in forms.
ROOM Integer The ID of the room assigned to this variable. Only returned if set.
CATEGORIES Array<Integer> The IDs of the categories assigned to this variable. Only returned if at least one category is set.

Types

These are the possible values for TYPE.

Type Description
FLOAT
INTEGER
BOOL
ENUM Data type is Integer. The value as an index to one of the options defined in VALUE_LIST.
STRING
ACTION Data type is Boolean. Always false when reading and always true in events. When writing, the value must be "true".

Example

(Struct length=10)
    {
      [DEFAULT]
      {
        (Integer) 0
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) LCD_SYMBOL
      }
      [MAX]
      {
        (Integer) 8
      }
      [MIN]
      {
        (Integer) 0
      }
      [OPERATIONS]
      {
        (Integer) 3
      }
      [TAB_ORDER]
      {
        (Integer) 2
      }
      [TYPE]
      {
        (String) ENUM
      }
      [UNIT]
      {
        (String)
      }
      [VALUE_LIST]
      {
        (Array length=9)
        {
          (String) NONE
          (String) BULB
          (String) SWITCH
          (String) WINDOW
          (String) DOOR
          (String) BLIND
          (String) SCENE
          (String) PHONE
          (String) BELL
        }
      }
    }
 

Paramset

The struct Paramset contains all values of a parameter set. One element is one value. The name of the element is the name of the parameter as defined in the XML file.

Example

(Struct length=350)
{
  [DISPLAY_TEMPERATUR_INFORMATION]
  {
    (Integer) 0
  }
  [DISPLAY_TEMPERATUR_UNIT]
  {
    (Integer) 0
  }
  [MODE_TEMPERATUR_REGULATOR]
  {
    (Integer) 0
  }
  [MODE_TEMPERATUR_VALVE]
  {
    (Integer) 0
  }
  [DISPLAY_TEMPERATUR_HUMIDITY_CHANGE]
  {
    (Integer) 1
  }
  [TEMPERATUR_COMFORT_VALUE]
  {
    (Float) 21
  }
  .
  .
  .
}
 

ParamsetDescription

The struct ParamsetDescription has one element for each parameter. The key is the parameter name. Each element is of type ParameterDescription.

Example

(Struct length=4)
{
  [PEER_NEEDS_BURST]
  {
    (Struct length=9)
    {
      [DEFAULT]
      {
        (Boolean) 0
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) PEER_NEEDS_BURST
      }
      [MAX]
      {
        (Boolean) 1
      }
      [MIN]
      {
        (Boolean) 0
      }
      [OPERATIONS]
      {
        (Integer) 3
      }
      [TAB_ORDER]
      {
        (Integer) 0
      }
      [TYPE]
      {
        (String) BOOL
      }
      [UNIT]
      {
        (String)
      }
    }
  }
  [EXPECT_AES]
  {
    (Struct length=9)
    {
      [DEFAULT]
      {
        (Boolean) 0
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) EXPECT_AES
      }
      [MAX]
      {
        (Boolean) 1
      }
      [MIN]
      {
        (Boolean) 0
      }
      [OPERATIONS]
      {
        (Integer) 3
      }
      [TAB_ORDER]
      {
        (Integer) 1
      }
      [TYPE]
      {
        (String) BOOL
      }
      [UNIT]
      {
        (String)
      }
    }
  }
  [LCD_SYMBOL]
  {
    (Struct length=10)
    {
      [DEFAULT]
      {
        (Integer) 0
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) LCD_SYMBOL
      }
      [MAX]
      {
        (Integer) 8
      }
      [MIN]
      {
        (Integer) 0
      }
      [OPERATIONS]
      {
        (Integer) 3
      }
      [TAB_ORDER]
      {
        (Integer) 2
      }
      [TYPE]
      {
        (String) ENUM
      }
      [UNIT]
      {
        (String)
      }
      [VALUE_LIST]
      {
        (Array length=9)
        {
          (String) NONE
          (String) BULB
          (String) SWITCH
          (String) WINDOW
          (String) DOOR
          (String) BLIND
          (String) SCENE
          (String) PHONE
          (String) BELL
        }
      }
    }
  }
  [LCD_LEVEL_INTERP]
  {
    (Struct length=10)
    {
      [DEFAULT]
      {
        (Integer) 0
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) LCD_LEVEL_INTERP
      }
      [MAX]
      {
        (Integer) 5
      }
      [MIN]
      {
        (Integer) 0
      }
      [OPERATIONS]
      {
        (Integer) 3
      }
      [TAB_ORDER]
      {
        (Integer) 3
      }
      [TYPE]
      {
        (String) ENUM
      }
      [UNIT]
      {
        (String)
      }
      [VALUE_LIST]
      {
        (Array length=6)
        {
          (String) NONE
          (String) LIGHT
          (String) BLIND
          (String) MARQUEE
          (String) DOOR
          (String) WINDOW
        }
      }
    }
  }
}
 

ServerInfo

The struct ServerInfo describes a RPC client's RPC server (event server).

Enumerations Used in ServerInfo

Name Values Description
AuthType 0 none
1 basic

Members

Name Type Description
INTERFACE_ID String The interface ID as it was passed to init
HOSTNAME String The hostname or IP address of the RPC server used by Homegear. Might be different from the hostname/address passed to init.
PORT String The port of the RPC server
PATH String The path part of the URL (e. g. /RPC2).
LASTPACKETSENT Integer The time (unix time stamp) the last packet was sent successfully (no communication or RPC error) to the client's RPC server.
SSL Boolean "True" when "https" was passed to init
BINARY Boolean "True" when binary packets are used instead of XML-RPC
KEEP_ALIVE Boolean When "True", Homegear won't disconnect after receiving the response to a packet
USE_ID Boolean When "True", Homegear sends device's id instead of the serial number in broadcast packets
SUBSCRIBE_PEERS Boolean When "True", Homegear only sends events of peers subscribed with subscribePeers to the event server.

The following settings are defined in "rpcclients.conf".

Name Type Description
FORCESSL Boolean When "True", Homegear doesn't accept unencrypted connections from this client.
AUTH_TYPE AuthType The authentication type Homegear uses to connect to the RPC server.
VERIFICATION_HOSTNAME String When certificate verification is enabled, the hostname of the server certifacte has to match this hostname.
VERIFY_CERTIFICATE Boolean "True" when certificate verification is enabled

Example

(Array length=1)
{
  (Struct length=7)
  {
    [BINARY]
    {
      (Boolean) 0
    }
    [HOSTNAME]
    {
      (String) 127.0.0.1
    }
    [INTERFACE_ID]
    {
      (String) IPS
    }
    [KEEP_ALIVE]
    {
      (Boolean) 0
    }
    [LASTPACKETSENT]
    {
      (Integer) 1393069381
    }
    [PATH]
    {
      (String) /RPC2
    }
    [PORT]
    {
      (String) 5544
    }
    [SSL]
    {
      (Boolean) 0
    }
  }
}
 

Defined by XML-RPC Standard

system.getCapabilities

Signatures

Struct system.getCapabilities()

Description

This method lists the RPC capabilities of the Homegear RPC server.

Parameters

This method has no parameters.

Return Value

The method returns a struct, and each element in this struct describes one capability.

Each element is, in turn, a struct with two fields:

  • specUrl (string): The URL leading to a description of the capability
  • specVersion (integer): The version used

Example Output

system.getCapabilities
(Struct length=3)
{
  [xmlrpc]
  {
    (Struct length=2)
    {
      [specUrl]
      {
        (String) http://www.xmlrpc.com/spec
      }
      [specVersion]
      {
        (Integer) 1
      }
    }
  }
  [faults_interop]
  {
    (Struct length=2)
    {
      [specUrl]
      {
        (String) http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
      }
      [specVersion]
      {
        (Integer) 20010516
      }
    }
  }
  [introspection]
  {
    (Struct length=2)
    {
      [specUrl]
      {
        (String) http://scripts.incutio.com/xmlrpc/introspection.html
      }
      [specVersion]
      {
        (Integer) 1
      }
    }
  }
}
 

system.listMethods

Signatures

Array system.listMethods()

Description

This method either lists all RPC methods that the Homegear RPC server knows or, if it is sent by Homegear's RPC client, requests all methods that the RPC event server knows.

Parameters

This method has no parameters.

Return Value

The method returns an array of strings. Each element in the array is a function name.

Example Output

system.listMethods()
(Array length=34)
{
  (String) addDevice
  (String) addLink
  (String) deleteDevice
  (String) deleteMetadata
  (String) getAllMetadata
  (String) getDeviceDescription
  (String) getInstallMode
  (String) getKeyMismatchDevice
  (String) getLinkInfo
  (String) getLinkPeers
  (String) getLinks
  (String) getMetadata
  (String) getParamset
  (String) getParamsetDescription
  (String) getParamsetId
  (String) getServiceMessages
  (String) getValue
  (String) init
  (String) listBidcosInterfaces
  (String) listDevices
  (String) listTeams
  (String) logLevel
  (String) putParamset
  (String) removeLink
  (String) setInstallMode
  (String) setLinkInfo
  (String) setMetadata
  (String) setTeam
  (String) setValue
  (String) system.getCapabilities
  (String) system.listMethods
  (String) system.methodHelp
  (String) system.methodSignature
  (String) system.multicall
}
 

system.methodHelp

Signatures

String system.methodHelp(String methodName)

Description

This method returns the description text of an RPC method.

Parameters

NameTypeDescriptionExample
methodNameStringThe name of the RPC method
createDevice

Return Value

It returns a description string or error -32602 if the method was not found.

Example Output

system.methodHelp("system.getCapabilities")
(String) Lists server's RPC capabilities.
 

system.methodSignature

Signatures

Array system.methodSignature(String methodName)

Description

This method returns the signature of an RPC method.

Parameters

NameTypeDescriptionExample
methodNameStringThe name of the method
getLinks

Return Value

The method returns an array of signatures, and each of these signature is also an array. The first element in each array of a signature is the return type, and all other elements are the parameter types.

Errors

CodeDescription
-32602Method not found

Example Output

system.methodSignature("getLinks")
(Array length=3)
{
  (Array length=1)
  {
    (String) array
  }
  (Array length=2)
  {
    (String) array
    (String) string
  }
  (Array length=3)
  {
    (String) array
    (String) string
    (String) i4
  }
}
 

system.multicall

Signatures

Array system.multicall(Array methods)

Description

This method can be used to call multiple RPC methods at the same time. Doing so can speed up RPC communication because there is no latency between the RPC calls.

Parameters

NameTypeDescriptionExample
methodsArrayThis is an array of structs. Each struct represents one method and has two fields: methodName and params
Array
( 
  Struct
  ( 
    [methodName]
    (
      (String) getValue
    )
    [params]
    (
      Array
      ( 
        (String) JEQ0551288:2
        (String) SETPOINT
      )
    )
  )
  Struct
  ( 
    [methodName]
    (
      (String) getValue
    )
    [params]
    (
      Array
      ( 
        (String) JEQ0552109:2
        (String) SETPOINT
      )
    )
  )
)
methodNameStringThe name of the method you want to call
getValue
paramsArrayArray of the parameters that should be passed to the method
Array
(
  (String) JEQ0551288:2
  (String) SETPOINT
)

Return Value

It returns an array consisting of the method responses. Each element is one response.

Example Output

system.multicall(
    (Array length=2)
    {
      (Struct length=2)
      {
        [methodName]
        {
          (String) getValue
        }
        [params]
        {
          (Array length=2)
          {
            (String) JEQ0551288:2
            (String) SETPOINT
          }
        }
      }
      (Struct length=2)
      {
        [methodName]
        {
          (String) getValue
        }
        [params]
        {
          (Array length=2)
          {
            (String) JEQ0534326:2
            (String) SETPOINT
          }
        }
      }
    }
)
(Array length=2)
{
  (Float) 21
  (Float) 21
}
 

General

getInstanceId

Signatures

String getInstanceId()

Description

This method returns the unique Homegear instance ID. The ID is created on first Homegear start and stored in the database. It never changes unless the database is recreated or manually updated.

Parameters

This method has no parameters.

Return Values

Returns the unique instance ID as String.

 

getServiceMessages

Signatures

(1) Array<Struct> getServiceMessages(Boolean newFormat, String language)
(2) Array<Array> getServiceMessages(Boolean newFormat, String language)

Description

This method returns all service messages that are currently active in Homegear (device unreachable, config pending, low battery, sabotage, ...).

Signature (1) is returned when newFormat is set to true. Signature (2) is returned, when it is set to false.

Parameters

newFormat

Recommended. If true, Homegear returns the peer ID instead of the serial number, global and family service messages and more information. By default, the deprecated old format is returned for compatibility reasons.

language

The language to return service messages for. E. g. en, en-US or de-DE.

Return Values

This methon returns an Array, and each element in the Array is a service message. If newFormat is true, each element is a Struct with the following elements:

Key Type Types Optional Description
TYPE Integer no 0 for global, 1 for family and 2 for device service messages.
PRIORITY Integer 0, 1, 2 no 1: critical, 2: error, 3: warning, 4: info, 5: debug
TIMESTAMP Integer 0, 1, 2 no The unix timestamp in seconds of the timepoint the service message was set.
FAMILY_ID Integer 1 no The ID of the family that created the service message.
INTERFACE String 1 yes When the service message is associated to a communication interface, the interface ID is set here.
PEER_ID Integer 2 no The ID of the peer that created the service message.
CHANNEL Integer 2 no The channel the service message is associated with.
VARIABLE String 2 no The variable the service message is associated with.
MESSAGE_ID Integer 0, 1 no An message ID to identify the service message. The combination of MESSAGE_ID and MESSAGE_SUBID is unique.
MESSAGE_SUBID String 0, 1 no A sub ID to indentify the service message. The combination of MESSAGE_ID and MESSAGE_SUBID is unique.
MESSAGE String 0, 1, 2 no The translated service message. If language is not specified, a Struct with all translations is returned. If a service message can be set multiple times (e. g. communication module service messages), a unique identifier is appended separated by a . (dot).
DATA Variant 0, 1 yes Additional data associated with the service message.
VALUE Boolean 0, 1, 2 no The value of the service message.

If newFormat is false or not set, the depracated old format is returned.

Exceptions

Code Description
-1 The room is unknown.
 

getVersion

Signatures

String getVersion()

Description

This method returns the installed version of Homegear.

Parameters

This method has no parameters.

Return Value

Returns the installed version of Homegear

Example Output

getVersion()
(String) Homegear 0.4.3
 

logLevel

Signatures

Integer logLevel()
Integer logLevel(Integer level)

Description

This method gets or sets the current log level.

Parameters

NameTypeDescriptionExample
levelIntegerThis is the log level that you want to set. The following are valid values:
  • 0: Log nothing
  • 1: Critical
  • 2: Error
  • 3: Warning
  • 4: Info
  • 5: Debug
Do not use "debug" for normal operation because it makes Homegear perform more slowly.
4

Return Value

Returns the current log level as an integer

Example Output

logLevel()
(Integer) 4
 

runScript

Signatures

Integer runScript(String filename)
Integer runScript(String filename, Boolean wait)
Integer runScript(String filename, String arguments)
Integer runScript(String filename, String arguments, Boolean wait)

Description

This method executes a script located in the script directory (default script directory is /var/lib/homegear/scripts). Files ending with .php, .php5 and .php7 are executed by the internal script engine. You can also execute all other programs or scripts in this directory as well.

Parameters

NameTypeDescriptionExample
filenameStringThe name of the script file in the scripts directory. You can specify subdirectories of the scripts directory before the file name.
Subdir/MyScript.sh
waitBooleanIf set to true waits for the script to finish. Otherwise the method returns immediately. Default is true.
true
argumentsStringThe arguments to pass to the script.
-u -a

Return Value

Returns the exit code of the program or script on success. If wait is false, 0 is returned when the script is started successfully.

Errors

CodeDescription
-32400Error starting script.
 

setLanguage

Signatures

Void setLanguage(String language)

Description

This method sets the language of the connection to return locale dependend strings in some RPC methods.

Parameters

NameTypeDescriptionExample
languageStringThe language code to set (first the ISO 639 language code followed by "-" and the ISO 3166 country code).
de-DE

Return Value

Returns Void on success
 

writeLog

Signatures

Void writeLog(String message)
Void writeLog(String message, Integer logLevel)

Description

This method writes a message to Homegear's log.

Parameters

NameTypeDescriptionExample
messageStringThis is the message you want to write to the log file. The date is automatically prepended.
My message
logLevelIntegerThis is the log level of the message. If Homegear's log level value is lower than this value, no message is logged. Valid values are:
  • 1: Critical
  • 2: Error
  • 3: Warning
  • 4: Info
  • 5: Debug
4

Return Value

Always returns Void
 

Database

deleteData

Signatures

Void deleteData(String component)
Void deleteData(String component, String key)

Description

This method deletes previously stored data from Homegear's key-value database.

Parameters

NameTypeDescriptionExample
componentStringThe name of the component to get values for as used in setData().
myaddon
keyStringThe key as defined in setData(). If ommited all values for the component are returned.
mydata

Return Value

Returns Void on success
 

getData

Signatures

Variant getData(String component)
Variant getData(String component, String dataId)

Description

This method returns data that was previously stored in Homegear's key-value database with setData().

Parameters

NameTypeDescriptionExample
componentStringThe name of the component to get values for as used in setData().
myaddon
keyStringThe key as defined in setData(). If ommited all values for the component are returned.
myData

Return Value

When key is specified the method returns the stored element. When only component is specified and key ommited the method returns a struct with the key-value pairs.

Example Output

Example 1
getData("mycomponent", "mykey")
(Integer64) 12
Example 2
getData("mycomponent")
(Struct length=2)
{
  [mykey]
  {
    (Integer64) 12
  }
  [mykey2]
  {
    (Array length=2)
    {
      (String) Hello
      (String) World
    }
  }
}
 

setData

Signatures

Void setData(String component, String key, Variant value)

Description

This method can be used to store data in Homegear's key-value database.

Parameters

NameTypeDescriptionExample
componentStringThe name of the component to store data for. Make sure it is unique. The maximum length are 250 characters.
myaddon
keyStringA name of your choice to access your data. The maximum length are 250 characters.
"mydata"
valueVariantThe value you want to store
43

Return Value

Returns Void on success

Errors

CodeDescription
-32602component or key are longer than 250 characters.
-32500The limit of 1 million data entries has been reached.
 

Devices

activateLinkParamset

Signatures

Void activateLinkParamset(Integer peerId, Integer channel, Integer remotePeerId, Integer remoteChannel)
Void activateLinkParamset(Integer peerId, Integer channel, Integer remotePeerId, Integer remoteChannel, Boolean longPress)

Description

This method can be used to simulate a remote key press. For most cases, setValue should be sufficient. Use "activeLinkParamset" if you want to execute commands that can be configured only using the link parameter set.

Deprecated - For compatability only
Void activateLinkParamset(String address, String remoteAddress)
Void activateLinkParamset(String address, String remoteAddress, Boolean longPress)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the actuator
131
channelIntegerThe channel of the actuator
1
remotePeerIdIntegerThe ID of a peer linked to the actuator or "0" if you want to use a virtual peer
1
remoteChannelIntegerThe channel of a remote peer; use the same "channel" value if a virtual peer is specified.
1
addressStringThe serial number and channel of the actuator separated by colon.
JEQ0578372:1
remoteAddressStringThe serial number and channel of a remote peer separated by colon.
LEQ0053372:1
longPressBooleanSet to "true" to simulate a long key press. The default setting is "false".
true

Return Value

Returns Void on success.

Errors

CodeDescription
-2Device or channel is unknown.
-3Peers are not peered to each other.
-32400Peer does not support this command.
 

Signatures

Void addLink(Integer senderId, Integer senderChannel, Integer receiverId, Integer receiverChannel)
Void addLink(Integer senderId, Integer senderChannel, Integer receiverId, Integer, receiverChannel, String name, String description)

Description

This method links two devices so that they can send commands to each other directly. This only works if supported by the device family.

Deprecated - For compatability only
Void addLink(String senderAddress, String receiverAddress)
Void addLink(String senderAddress, String receiverAddress, String name, String description)

Parameters

NameTypeDescriptionExample
senderIdIntegerThe ID of the sending peer (e.g. a remote)
12
senderChannelIntegerThe channel of the sending peer or "-1"
1
receiverIdIntegerThe ID of the receiving peer (e.g. a switch)
1
receiverChannelIntegerThe channel of the receiving peer or "-1"
1
senderAddressStringThe serial number and channel of the sending device (e.g. a remote), seperated by colon
JEQ0304693:7
receiverAddressStringThe serial number and channel of the receiving device (e.g. a switch), seperated by colon
JEQ0098488:1
nameStringA descriptive name for the link
Living Room - Light
descriptionStringA short description of the link
This is supposed to be a short description, but I have no idea what to write here...

Return Value

Returns Void on success

Errors

CodeDescription
-2At least one of the devices or channels is unknown.
 

copyConfig

Signatures

Void copyConfig(Integer sourcePeerId, Integer sourceChannel, Integer targetPeerId, Integer targetChannel)

Description

This method copies configuration data (the MASTER parameter set) from one channel to another. If a parameter doesn't exist in the target parameter set, it is ignored.

Deprecated - For compatability only
Void copyConfig(String sourceAddress, String targetAddress)

Parameters

NameTypeDescriptionExample
sourcePeerIdIntegerThe id of the peer to copy the parameter set from
131
sourceChannelIntegerThe channel to copy the parameter set from
3
targetPeerIdIntegerThe id of the peer to copy the parameter set to
135
targetChannelIntegerThe channel to copy the parameter set to
2
sourceAddressStringThe serial number and channel of the device to copy the parameter set from (separated by colon)
JEQ0578372:1
targetAddressStringThe serial number and channel of the device to copy the parameter set to (separated by colon)
LEQ0053372:1

Return Value

Returns Void on success.

Errors

CodeDescription
-2Device or channel is unknown.
-3At least one of the parameter sets is unknown.
 

deleteDevice

Signatures

Void deleteDevice(Integer peerId, Integer flags)

Description

This method unpairs a device from Homegear or resets it to factory defaults. Some devices need to be in pairing mode for this to succeed - except the flag "DEFER" is used.

Deprecated - For compatability only
Void deleteDevice(String address, Integer flags)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe id of the peer to delete
51
addressStringThe serial number of the device to delete
JEQ0578372
flagsIntegerThe following flags are available:
  • 1 (RESET): Resets the device to factory defaults (if possible). If this flag is not set the device is just unpaired without being reset.
  • 2 (FORCE): Removes the device from Homegear. Homegear will try once to unpair or reset the device. If that fails the device is just removed from the central without any further attempts to unpair it.
  • 4 (DEFER): Unpair the device when the next packet is received that can trigger unpairing.
  • 8 (DELETE_FROM_GATEWAY): Also deletes the device from underlying gateway (if possible).
5 (RESET and DEFER)

Return Value

Returns Void on success.

Errors

CodeDescription
-2Device or channel is unknown.
 

getAllConfig

Signatures

Struct getAllConfig()
Struct getAllConfig(Integer peerId)

Description

This method returns all configuration parameter values and information about all configuration parameters for one or all peers. Variables are not returned. To get all variables, call getAllValues.

Parameters

NameTypeDescriptionExample
peerIdIntegerWhen specified, only variables of this peer are returned.
12

Return Value

This returns an array of structs. One struct is returned for each device. The struct has the following elements:
  • ADDRESS: The serial number of the device (e. g. JEQ0471872)
  • ID: The ID of the device (e. g. 12)
  • FAMILIY: The ID of the device family (e. g. 0 for HomeMatic BidCoS)
  • TYPE: The type string of the device (e. g. HMW-LC-Dim1L-DR)
  • TYPE_ID: The type ID of the device (e. g. 25)
  • NAME: The user-defined name of the device (e. g. "Living room - light")
  • CHANNELS: This is an array containing one element for each channel of the device. Each element is a struct with the following items:
    • INDEX: The channel index
    • TYPE: The channel type (e. g. KEY)
    • PARAMSET: This is a struct with one element for each parameter. The name of each item is the name of the parameter. The parameter struct has the following elements:
      • VALUE: The value of the parameter
      • TYPE: The parameter type (BOOL, ACTION, INTEGER, ENUM, STRING, FLOAT)
      • MIN: The minimum possible numeric value (only for INTEGER, ENUM, or FLOAT)
      • MAX: The maximum possible numeric value (only for INTEGER, ENUM, or FLOAT)
      • VALUE_LIST: It is an array with string descriptions of all possible values and is only for ENUM.
      • SPECIAL: This is only for INTEGER or FLOAT and is an array of structs. Each struct has two elements:
        • ID: A string description of the special value
        • VALUE: The special value

Errors

CodeDescription
-2Peer is unknown.

Example Output

getAllConfig()
(Array length=20)
{
  (Struct length=7)
  {
    [ADDRESS]
    {
      (String) LEQ1323555
    }
    [CHANNELS]
    {
      (Array length=11)
      {
        (Struct length=3)
        {
          [INDEX]
          {
            (Integer) 0
          }
          [PARAMSET]
          {
            (Struct length=2)
            {
              [ROAMING]
              {
                (Struct length=2)
                {
                  [TYPE]
                  {
                    (String) BOOL
                  }
                  [VALUE]
                  {
                    (Boolean) 0
                  }
                }
              }
              .
              .
              .
            }
          }
          [TYPE]
          {
            (String) MAINTENANCE
          }
        }
        (Struct length=3)
        {
          [INDEX]
          {
            (Integer) 1
          }
          [PARAMSET]
          {
            (Struct length=2)
            {
              [TEXTLINE_1]
              {
                (Struct length=2)
                {
                  [TYPE]
                  {
                    (String) STRING
                  }
                  [VALUE]
                  {
                    (String) Textblock 1
                  }
                }
              }
              .
              .
              .
            }
          }
          [TYPE]
          {
            (String) KEY
          }
        }
        .
        .
        .
      }
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [ID]
    {
      (Integer) 33
    }
    [NAME]
    {
      (String) 
    }
    [TYPE]
    {
      (String) HM-Dis-WM55
    }
    [TYPE_ID]
    {
      (Integer) 211
    }
  }
  (Struct length=7)
  {
    [ADDRESS]
    {
      (String) LEQ1173505
    }
    [CHANNELS]
    {
      .
      .
      .
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [ID]
    {
      (Integer) 42
    }
    [NAME]
    {
      (String) 
    }
    [TYPE]
    {
      (String) HM-Sec-SCo
    }
    [TYPE_ID]
    {
      (Integer) 199
    }
  }
  .
  .
  .
}
 

getAllValues

Signatures

Struct getAllValues()
Struct getAllValues(Boolean returnWriteOnlyVariables)
Struct getAllValues(Integer peerId)
Struct getAllValues(Integer peerId, Boolean returnWriteOnlyVariables)
Struct getAllValues(Array<Integer> peerIds)
Struct getAllValues(Array<Integer>, Boolean returnWriteOnlyVariables)

Description

This method returns all variable values and information about all variables for one or all peers. Configuration parameters are not returned. To get all configuration parameters, call getAllConfig.

Parameters

NameTypeDescriptionExample
peerIdIntegerWhen specified, only variables of this peer are returned.
12
peerIdsArray<Integer>When specified, only variables of these peers are returned.
[ 10, 11, 12 ]
returnWriteOnlyVariablesBooleanWhen specifed, writeOnly variables are also returned.
true

Return Value

This returns an array of structs, and one struct is returned for each device. The struct has the following elements:
  • ADDRESS: The serial number of the device (e. g. JEQ0471872)
  • ID: The ID of the device (e. g. 12)
  • FAMILIY: The ID of the device family (e. g. 0 for HomeMatic BidCoS)
  • TYPE: The type string of the device (e. g. HMW-LC-Dim1L-DR)
  • TYPE_ID: The type ID of the device (e. g. 25)
  • NAME: The user-defined name of the device (e. g. "Living room - light")
  • CHANNELS: An array with one element for each channel of the device, where each element is a struct with the following items:
    • INDEX: The channel index
    • TYPE: The channel type (e. g. KEY)
    • PARAMSET: A struct with one element for each variable, and the name of each item is the name of the variable. The variable struct has the following elements:
      • VALUE: The value of the variable
      • READABLE: "true" if the variable is readable (there are writeonly variables)
      • WRITEABLE: "true" if the variable is writeable
      • TYPE: The variable type (BOOL, ACTION, INTEGER, ENUM, STRING, FLOAT)
      • MIN: The minimum possible numeric value (only for INTEGER, ENUM, or FLOAT)
      • MAX: The maximum possible numeric value (only for INTEGER, ENUM, or FLOAT)
      • VALUE_LIST: This is an array with string descriptions of all possible values and is only for ENUM.
      • SPECIAL: This is an array of structs and is only for INTEGER or FLOAT. Each struct has two elements:
        • ID: A string description of the special value
        • VALUE: The special value

Errors

CodeDescription
-2Peer is unknown.

Example Output

getAllValues()
(Array length=20)
{
  (Struct length=7)
  {
    [ADDRESS]
    {
      (String) LEQ1323555
    }
    [CHANNELS]
    {
      (Array length=11)
      {
        (Struct length=3)
        {
          [INDEX]
          {
            (Integer) 0
          }
          [PARAMSET]
          {
            (Struct length=9)
            {
              [CENTRAL_ADDRESS_SPOOFED]
              {
                (Struct length=6)
                {
                  [MAX]
                  {
                    (Integer) 1
                  }
                  [MIN]
                  {
                    (Integer) 0
                  }
                  [TYPE]
                  {
                    (String) ENUM
                  }
                  [VALUE]
                  {
                    (Integer) 0
                  }
                  [VALUE_LIST]
                  {
                    (Array length=2)
                    {
                      (String) UNSET
                      (String) CENTRAL_ADDRESS_SPOOFED
                    }
                  }
                  [WRITEABLE]
                  {
                    (Boolean) 1
                  }
                }
              }
              .
              .
              .
            }
          }
          [TYPE]
          {
            (String) MAINTENANCE
          }
        }
        (Struct length=3)
        {
          [INDEX]
          {
            (Integer) 1
          }
          [PARAMSET]
          {
            (Struct length=5)
            {
              [INSTALL_TEST]
              {
                (Struct length=3)
                {
                  [TYPE]
                  {
                    (String) ACTION
                  }
                  [VALUE]
                  {
                    (Boolean) 0
                  }
                  [WRITEABLE]
                  {
                    (Boolean) 0
                  }
                }
              }
              .
              .
              .
            }
          }
          [TYPE]
          {
            (String) KEY
          }
        }
      }
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [ID]
    {
      (Integer) 33
    }
    [NAME]
    {
      (String) 
    }
    [TYPE]
    {
      (String) HM-Dis-WM55
    }
    [TYPE_ID]
    {
      (Integer) 211
    }
  }
  (Struct length=7)
  {
    [ADDRESS]
    {
      (String) LEQ1173505
    }
    [CHANNELS]
    {
      .
      .
      .
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [ID]
    {
      (Integer) 42
    }
    [NAME]
    {
      (String) 
    }
    [TYPE]
    {
      (String) HM-Sec-SCo
    }
    [TYPE_ID]
    {
      (Integer) 199
    }
  }
}
 

getDeviceDescription

Signatures

DeviceDescription getDeviceDescription(Integer peerId, Integer channel)
DeviceDescription getDeviceDescription(Integer peerId, Integer channel, Array<String> fields)

Description

This method returns the a struct of type DeviceDescription of the specified device or channel.

Deprecated - For compatability only
DeviceDescription getDeviceDescription(String address)
DeviceDescription getDeviceDescription(String address, Array<String> fields)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to return the device description for.
12
channelIntegerThe channel of the peer to return the device description for.
1
addressStringThe serialnumber and channel of the device seperated by colon.
JEQ0578372:1
fieldsArrayWhen fields is not empty, only the struct elements defined in the array (e. g. ID or TYPE) are returned. This saves ressources. Some elements like DESCRIPTION or LONG_DESCRIPTION are only returned when explicitly requested through this variable.
[ "ID", "TYPE" ]

Return Value

Returns a struct of type DeviceDescription

Errors

CodeDescription
-2Peer or channel is unknown.

Example Output

getDeviceDescription(89, 0)
(Struct length=15)
{
  [ADDRESS]
  {
    (String) ITD0000012F:0
  }
  [AES_ACTIVE]
  {
    (Integer) 0
  }
  [CATEGORIES]
  {
    (Array length=2)
    {
      (Integer) 5
      (Integer) 7
    }
  }
  [CHANNEL]
  {
    (Integer) 0
  }
  [DIRECTION]
  {
    (Integer) 0
  }
  [FAMILY]
  {
    (Integer) 16
  }
  [FLAGS]
  {
    (Integer) 3
  }
  [ID]
  {
    (Integer) 3
  }
  [INDEX]
  {
    (Integer) 0
  }
  [LINK_SOURCE_ROLES]
  {
    (String) 
  }
  [LINK_TARGET_ROLES]
  {
    (String) 
  }
  [PARAMSETS]
  {
    (Array length=2)
    {
      (String) MASTER
      (String) VALUES
    }
  }
  [PARENT]
  {
    (String) ITD0000012F
  }
  [PARENT_TYPE]
  {
    (String) IT-Switch
  }
  [ROOM]
  {
    (Integer) 2
  }
  [TYPE]
  {
    (String) MAINTENANCE
  }
  [VERSION]
  {
    (Integer) 1
  }
}
 

getDeviceInfo

Signatures

Array<Struct> getDeviceInfo()
Struct getDeviceInfo(Integer peerId)
Struct getDeviceInfo(Integer peerId, Array<String> fields)

Description

This method returns an array of structs with one entry for each device paired to Homegear. In contrast to listDevices, this method contains non static information.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to return the device information for.
12
fieldsArray<String>When fields is not empty, only the struct elements defined in the array (e. g. "INTERFACE" or "NAME") are returned. This saves ressources.
[ "INTERFACE", "NAME" ]

Return Value

Returns an array of structs. Each struct has the elemends "ID", "INTERFACE", "NAME" and "RSSI". In case getDeviceInfo() is called with the peer ID specified, only one struct is returned.

Errors

CodeDescription
-2Peer is unknown.

Example Output

Example 1
getDeviceInfo()
(Array length=2)
{
  (Struct length=4)
  {
    [ID]
    {
      (Integer) 4
    }
    [INTERFACE]
    {
      (String) CRC
    }
    [NAME]
    {
      (String) 1. OG Flur
    }
    [RSSI]
    {
      (Integer) -77
    }
  }
  (Struct length=4)
  {
    [ID]
    {
      (Integer) 7
    }
    [INTERFACE]
    {
      (String) CUL
    }
    [NAME]
    {
      (String) 1. OG Schlafzimmer
    }
    [RSSI]
    {
      (Integer) -65
    }
  }
}
Example 2
getDeviceInfo(3)
(Struct length=3)
{
  [ID]
  {
    (Integer64) 3
  }
  [NAME]
  {
    (String) 
  }
  [RSSI]
  {
    (Integer64) 0
  }
}
 

getLinkInfo

Signatures

Struct getLinkInfo(Integer senderId, Integer senderChannel, Integer receiverId, Integer receiverChannel)

Description

This method returns the name and description of a direct device link.

Deprecated - For compatability only
Struct getLinkInfo(String senderAddress, String receiverAddress)

Parameters

NameTypeDescriptionExample
senderIdIntegerThe ID of the sending peer (e. g. a remote).
12
senderChannelIntegerThe channel of the sending peer or "-1".
1
receiverIdIntegerThe ID of the receiving peer (e. g. a switch).
14
receiverChannelIntegerThe channel of the receiving peer or "-1".
1
senderAddressStringThe serial number and channel of the sending peer separated by colon.
JEQ0578372:1
remoteAddressStringThe serial number and channel of the receiving peer separated by colon.
LEQ0053372:1

Return Value

Returns a struct with two elements of type String: "NAME" and "DESCRIPTION".

Errors

CodeDescription
-2Link is unknown.

Example Output

getLinkInfo(89, 1, 114, 1)
(Struct length=2)
{
  [DESCRIPTION]
  {
    (String) My link description
  }
  [NAME]
  {
    (String) My link name
  }
}
 

getLinkPeers

Signatures

Array getLinkPeers(Integer peerId, Integer channel)

Description

This method returns an array of all peers a channel or peer is linked to.

Deprecated - For compatability only
Array getLinkPeers(String address)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to get links for.
12
channelIntegerThe channel to get the links for. If "-1" the links of all channels are returned.
1
addressStringThe serial number and channel of the peer to get the links for. When no channel is specified, the function returns the peers for all channels.
JEQ0578372:1

Return Value

Returns an array with one element for each peer. Each element again is an array containing the remote's peer id and channel.

Errors

CodeDescription
-2Device or channel are unknown.

Example Output

Example 1
getLinkPeers(27, 1)
(Array length=2)
{
  (Array length=2)
  {
    (Integer) 36
    (Integer) 1
  }
  (Array length=2)
  {
    (Integer) 36
    (Integer) 2
  }
}
Example 2
getLinkPeers("JEQ0739619:1")
(Array length=1)
{
  (String) JEQ0095676:1
}
 

Signatures

Array getLinks()
Array getLinks(Integer peerId)
Array getLinks(Integer peerId, Integer channel)
Array getLinks(Integer peerId, Integer channel, Integer flags)

Description

This method returns an array of type LinkDescription. When a peer but no channel is specified, it returns LinkDescription for all channels of the device. When no parameter is passed it returns LinkDescription for all peers and channels.

Deprecated - For compatability only
Array getLinks(String address)
Array getLinks(String address, Integer flags)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to get links for.
12
channelIntegerThe channel to get the links for. If "-1" the links of all channels are returned.
1
addressStringThe serial number and channel of the peer to get the links for. When no channel is specified, the function returns LinkDescription for all channels.
JEQ0578372:1
flagsIntegerThe following flags are available:
7

Return Value

Returns an array of type LinkDescription.

Errors

CodeDescription
-2Device or channel are unknown.

Example Output

getLinks(5, 1, 31)
(Array length=2)
{
  (Struct length=13)
  {
    [DESCRIPTION]
    {
      (String)
    }
    [FLAGS]
    {
      (Integer) 0
    }
    [NAME]
    {
      (String)
    }
    [RECEIVER]
    {
      (String) KEQ0192415:3
    }
    [RECEIVER_CHANNEL]
    {
      (Integer) 3
    }
    [RECEIVER_DESCRIPTION]
    {
      (Struct length=15)
      {
        [ADDRESS]
        {
          (String) KEQ0192415:3
        }
        [AES_ACTIVE]
        {
          (Integer) 0
        }
        [DIRECTION]
        {
          (Integer) 2
        }
        [FAMILY]
        {
          (Integer) 1
        }
        [FAMILY_STRING]
        {
          (String) HomeMatic Wired
        }
        [FLAGS]
        {
          (Integer) 1
        }
        [ID]
        {
          (Integer) 6
        }
        [INDEX]
        {
          (Integer) 3
        }
        [LINK_SOURCE_ROLES]
        {
          (String)
        }
        [LINK_TARGET_ROLES]
        {
          (String) SWITCH
        }
        [PARAMSETS]
        {
          (Array length=3)
          {
            (String) MASTER
            (String) VALUES
            (String) LINK
          }
        }
        [PARENT]
        {
          (String) KEQ0192415
        }
        [PARENT_TYPE]
        {
          (String) HMW-LC-Sw2-DR
        }
        [TYPE]
        {
          (String) SWITCH
        }
        [VERSION]
        {
          (Integer) 12
        }
      }
    }
    [RECEIVER_ID]
    {
      (Integer) 6
    }
    [RECEIVER_PARAMSET]
    {
      (Struct length=26)
      {
        [LONG_ACTION_TYPE]
        {
          (Integer) 1
        }
        [LONG_JT_OFF]
        {
          (Integer) 0
        }
        [LONG_JT_OFFDELAY]
        {
          (Integer) 3
        }
        [LONG_JT_ON]
        {
          (Integer) 2
        }
        [LONG_JT_ONDELAY]
        {
          (Integer) 1
        }
        [LONG_MULTIEXECUTE]
        {
          (Boolean) 1
        }
        [LONG_OFFDELAY_TIME]
        {
          (Float) 0
        }
        [LONG_OFF_TIME]
        {
          (Float) 1.6383e+07
        }
        [LONG_OFF_TIME_MODE]
        {
          (Integer) 1
        }
        [LONG_ONDELAY_TIME]
        {
          (Float) 0
        }
        [LONG_ON_TIME]
        {
          (Float) 1.6383e+07
        }
        [LONG_ON_TIME_MODE]
        {
          (Integer) 1
        }
        [LONG_TOGGLE_USE]
        {
          (Integer) 0
        }
        [SHORT_ACTION_TYPE]
        {
          (Integer) 1
        }
        [SHORT_JT_OFF]
        {
          (Integer) 0
        }
        [SHORT_JT_OFFDELAY]
        {
          (Integer) 3
        }
        [SHORT_JT_ON]
        {
          (Integer) 2
        }
        [SHORT_JT_ONDELAY]
        {
          (Integer) 1
        }
        [SHORT_OFFDELAY_TIME]
        {
          (Float) 0
        }
        [SHORT_OFF_TIME]
        {
          (Float) 1.6383e+07
        }
        [SHORT_OFF_TIME_MODE]
        {
          (Integer) 1
        }
        [SHORT_ONDELAY_TIME]
        {
          (Float) 0
        }
        [SHORT_ON_TIME]
        {
          (Float) 1.6383e+07
        }
        [SHORT_ON_TIME_MODE]
        {
          (Integer) 1
        }
        [SHORT_TOGGLE_USE]
        {
          (Integer) 0
        }
        [UI_HINT]
        {
          (String)
        }
      }
    }
    [SENDER]
    {
      (String) JEQ0151080:1
    }
    [SENDER_CHANNEL]
    {
      (Integer) 1
    }
    [SENDER_DESCRIPTION]
    {
      (Struct length=15)
      {
        [ADDRESS]
        {
          (String) JEQ0151080:1
        }
        [AES_ACTIVE]
        {
          (Integer) 0
        }
        [DIRECTION]
        {
          (Integer) 1
        }
        [FAMILY]
        {
          (Integer) 1
        }
        [FAMILY_STRING]
        {
          (String) HomeMatic Wired
        }
        [FLAGS]
        {
          (Integer) 1
        }
        [ID]
        {
          (Integer) 5
        }
        [INDEX]
        {
          (Integer) 1
        }
        [LINK_SOURCE_ROLES]
        {
          (String) SWITCH
        }
        [LINK_TARGET_ROLES]
        {
          (String)
        }
        [PARAMSETS]
        {
          (Array length=3)
          {
            (String) MASTER
            (String) VALUES
            (String) LINK
          }
        }
        [PARENT]
        {
          (String) JEQ0151080
        }
        [PARENT_TYPE]
        {
          (String) HMW-LC-Dim1L-DR
        }
        [TYPE]
        {
          (String) KEY
        }
        [VERSION]
        {
          (Integer) 11
        }
      }
    }
    [SENDER_ID]
    {
      (Integer) 5
    }
    [SENDER_PARAMSET]
    {
      (Struct length=0)
      {
      }
    }
  }
  (Struct length=13)
  {
    [DESCRIPTION]
    {
      (String) Blupp Blupp
    }
    [FLAGS]
    {
      (Integer) 0
    }
    [NAME]
    {
      (String) Bla Bla
    }
    [RECEIVER]
    {
      (String) KEQ0192415:4
    }
    [RECEIVER_CHANNEL]
    {
      (Integer) 4
    }
    [RECEIVER_DESCRIPTION]
    {
      (Struct length=15)
      {
        [ADDRESS]
        {
          (String) KEQ0192415:4
        }
        [AES_ACTIVE]
        {
          (Integer) 0
        }
        [DIRECTION]
        {
          (Integer) 2
        }
        [FAMILY]
        {
          (Integer) 1
        }
        [FAMILY_STRING]
        {
          (String) HomeMatic Wired
        }
        [FLAGS]
        {
          (Integer) 1
        }
        [ID]
        {
          (Integer) 6
        }
        [INDEX]
        {
          (Integer) 4
        }
        [LINK_SOURCE_ROLES]
        {
          (String)
        }
        [LINK_TARGET_ROLES]
        {
          (String) SWITCH
        }
        [PARAMSETS]
        {
          (Array length=3)
          {
            (String) MASTER
            (String) VALUES
            (String) LINK
          }
        }
        [PARENT]
        {
          (String) KEQ0192415
        }
        [PARENT_TYPE]
        {
          (String) HMW-LC-Sw2-DR
        }
        [TYPE]
        {
          (String) SWITCH
        }
        [VERSION]
        {
          (Integer) 12
        }
      }
    }
    [RECEIVER_ID]
    {
      (Integer) 6
    }
    [RECEIVER_PARAMSET]
    {
      (Struct length=26)
      {
        [LONG_ACTION_TYPE]
        {
          (Integer) 1
        }
        [LONG_JT_OFF]
        {
          (Integer) 0
        }
        [LONG_JT_OFFDELAY]
        {
          (Integer) 3
        }
        [LONG_JT_ON]
        {
          (Integer) 2
        }
        [LONG_JT_ONDELAY]
        {
          (Integer) 1
        }
        [LONG_MULTIEXECUTE]
        {
          (Boolean) 1
        }
        [LONG_OFFDELAY_TIME]
        {
          (Float) 0
        }
        [LONG_OFF_TIME]
        {
          (Float) 1.6383e+07
        }
        [LONG_OFF_TIME_MODE]
        {
          (Integer) 1
        }
        [LONG_ONDELAY_TIME]
        {
          (Float) 0
        }
        [LONG_ON_TIME]
        {
          (Float) 1.6383e+07
        }
        [LONG_ON_TIME_MODE]
        {
          (Integer) 1
        }
        [LONG_TOGGLE_USE]
        {
          (Integer) 0
        }
        [SHORT_ACTION_TYPE]
        {
          (Integer) 1
        }
        [SHORT_JT_OFF]
        {
          (Integer) 0
        }
        [SHORT_JT_OFFDELAY]
        {
          (Integer) 3
        }
        [SHORT_JT_ON]
        {
          (Integer) 2
        }
        [SHORT_JT_ONDELAY]
        {
          (Integer) 1
        }
        [SHORT_OFFDELAY_TIME]
        {
          (Float) 0
        }
        [SHORT_OFF_TIME]
        {
          (Float) 1.6383e+07
        }
        [SHORT_OFF_TIME_MODE]
        {
          (Integer) 1
        }
        [SHORT_ONDELAY_TIME]
        {
          (Float) 0
        }
        [SHORT_ON_TIME]
        {
          (Float) 1.6383e+07
        }
        [SHORT_ON_TIME_MODE]
        {
          (Integer) 1
        }
        [SHORT_TOGGLE_USE]
        {
          (Integer) 0
        }
        [UI_HINT]
        {
          (String)
        }
      }
    }
    [SENDER]
    {
      (String) JEQ0151080:1
    }
    [SENDER_CHANNEL]
    {
      (Integer) 1
    }
    [SENDER_DESCRIPTION]
    {
      (Struct length=15)
      {
        [ADDRESS]
        {
          (String) JEQ0151080:1
        }
        [AES_ACTIVE]
        {
          (Integer) 0
        }
        [DIRECTION]
        {
          (Integer) 1
        }
        [FAMILY]
        {
          (Integer) 1
        }
        [FAMILY_STRING]
        {
          (String) HomeMatic Wired
        }
        [FLAGS]
        {
          (Integer) 1
        }
        [ID]
        {
          (Integer) 5
        }
        [INDEX]
        {
          (Integer) 1
        }
        [LINK_SOURCE_ROLES]
        {
          (String) SWITCH
        }
        [LINK_TARGET_ROLES]
        {
          (String)
        }
        [PARAMSETS]
        {
          (Array length=3)
          {
            (String) MASTER
            (String) VALUES
            (String) LINK
          }
        }
        [PARENT]
        {
          (String) JEQ0151080
        }
        [PARENT_TYPE]
        {
          (String) HMW-LC-Dim1L-DR
        }
        [TYPE]
        {
          (String) KEY
        }
        [VERSION]
        {
          (Integer) 11
        }
      }
    }
    [SENDER_ID]
    {
      (Integer) 5
    }
    [SENDER_PARAMSET]
    {
      (Struct length=0)
      {
      }
    }
  }
}
 

getName

Signatures

String getName(Integer peerId)

Description

This method returns the name of a peer previously assigned using the CLI or by calling setName.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer you want to get the name for
131

Return Value

Returns the name on success.

Errors

CodeDescription
-2Peer is unknown.
 

getParamset

Signatures

Paramset getParamset(Integer peerId, Integer channel)
Paramset getParamset(Integer peerId, Integer channel, Integer remotePeerId, Integer remoteChannel)

Description

This method returns the configuration parameters of a peer's channel.

Deprecated - For compatability only
Paramset getParamset(String address, String paramsetType)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer.
12
channelIntegerThe channel to get the configuration parameters for.
1
remotePeerIdIntegerAn ID of a peer the peer is linked to. Used to return configuration parameters of a direct link between two peers.
14
remoteChannelIntegerThe channel of peer "remotePeerId" the peer is linked to.
1
addressStringThe serial number and channel of the peer separated by colon.
JEQ0578372:1
paramsetTypeString"MASTER", "VALUES" or "LINK".
MASTER

Return Value

Returns a struct of type Paramset.

Errors

CodeDescription
-2Device or channel unknown.
-3Parameter set is unknown.

Example Output

getParamset(23, 1, 58, 1)
(Struct length=36)
{
  [UI_HINT]
  {
    (String) 2
  }
  [SHORT_CT_OFFDELAY]
  {
    (Integer) 0
  }
  [SHORT_CT_ONDELAY]
  {
    (Integer) 0
  }
  [SHORT_CT_OFF]
  {
    (Integer) 0
  }
  [SHORT_CT_ON]
  {
    (Integer) 0
  }
  [SHORT_COND_VALUE_LO]
  {
    (Integer) 50
  }
  [SHORT_COND_VALUE_HI]
  {
    (Integer) 180
  }
  [SHORT_ONDELAY_TIME]
  {
    (Float) 0
  }
  [SHORT_ON_TIME]
  {
    (Float) 120
  }
  [SHORT_OFFDELAY_TIME]
  {
    (Float) 0
  }
  [SHORT_OFF_TIME]
  {
    (Float) 111600
  }
  [SHORT_ON_TIME_MODE]
  {
    (Integer) 0
  }
  [SHORT_OFF_TIME_MODE]
  {
    (Integer) 0
  }
  [SHORT_ACTION_TYPE]
  {
    (Integer) 1
  }
  [SHORT_JT_OFF]
  {
    (Integer) 1
  }
  [SHORT_JT_ON]
  {
    (Integer) 2
  }
  [SHORT_JT_OFFDELAY]
  {
    (Integer) 2
  }
  [SHORT_JT_ONDELAY]
  {
    (Integer) 0
  }
  [LONG_CT_OFFDELAY]
  {
    (Integer) 0
  }
  [LONG_CT_ONDELAY]
  {
    (Integer) 0
  }
  [LONG_CT_OFF]
  {
    (Integer) 0
  }
  [LONG_CT_ON]
  {
    (Integer) 0
  }
  [LONG_COND_VALUE_LO]
  {
    (Integer) 50
  }
  [LONG_COND_VALUE_HI]
  {
    (Integer) 100
  }
  [LONG_ONDELAY_TIME]
  {
    (Float) 0
  }
  [LONG_ON_TIME]
  {
    (Float) 111600
  }
  [LONG_OFFDELAY_TIME]
  {
    (Float) 0
  }
  [LONG_OFF_TIME]
  {
    (Float) 111600
  }
  [LONG_ON_TIME_MODE]
  {
    (Integer) 0
  }
  [LONG_OFF_TIME_MODE]
  {
    (Integer) 0
  }
  [LONG_MULTIEXECUTE]
  {
    (Integer) 1
  }
  [LONG_ACTION_TYPE]
  {
    (Integer) 0
  }
  [LONG_JT_OFF]
  {
    (Integer) 4
  }
  [LONG_JT_ON]
  {
    (Integer) 4
  }
  [LONG_JT_OFFDELAY]
  {
    (Integer) 4
  }
  [LONG_JT_ONDELAY]
  {
    (Integer) 4
  }
}
 

getParamsetDescription

Signatures

(1) ParamsetDescription getParamsetDescription(Integer peerId, Integer channel, String paramsetType)
(2) ParamsetDescription getParamsetDescription(Integer peerId, Integer channel, Integer remotePeerId, Integer remoteChannel)
(3) ParamsetDescription getParamsetDescription(Integer familyId, Integer deviceTypeId, Integer firmwareVersion, Integer channel, String paramsetType)

Description

This method returns information about a device's or channel's parameter set. Signature (1), (2) and (4) return paramsetDescription of paired peers. Signature (3) returns paramsetDescription of devices known but not paired to Homegear.

Deprecated - For compatability only
(4) ParamsetDescription getParamsetDescription(String address, String paramsetType)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer.
12
channelIntegerThe channel to get the parameter set description for.
1
remotePeerIdIntegerAn ID of a peer the peer is linked to. Used to return the description of a link parameter set, which contains configuration parameters specific to direct links.
14
remoteChannelIntegerThe channel of peer "remotePeerId" the peer is linked to.
1
paramsetTypeString"MASTER", "VALUES" or "LINK". "MASTER" contains configuration parameters, "VALUES" contains variables and "LINK" contains configuration parameters for direct links with the specified channel.
MASTER
familyIdIntegerThe ID of the device family the device to get the parameter set for belongs to.
4
deviceTypeIdIntegerThe type number of the device as defined in the device description file.
25
firmwareVersionIntegerThe firmware version of the device to get the parameter set for. For some devices there are multiple device descriptions depending on the firmware version.
16
addressStringThe serial number and channel of the peer separated by colon.
JEQ0578372:1

Return Value

Returns a struct of type paramsetDescription.

Errors

CodeDescription
-2Device or channel unknown.
-3Parameter set is unknown.

Example Output

getParamsetDescription(27, 1, "VALUES")
(Struct length=3)
{
  [STATE]
  {
    (Struct length=9)
    {
      [CONTROL]
      {
        (String) DOOR_SENSOR.STATE
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) STATE
      }
      [MAX]
      {
        (Boolean) 1
      }
      [MIN]
      {
        (Boolean) 0
      }
      [OPERATIONS]
      {
        (Integer) 5
      }
      [TAB_ORDER]
      {
        (Integer) 0
      }
      [TYPE]
      {
        (String) BOOL
      }
      [UNIT]
      {
        (String)
      }
    }
  }
  [LOWBAT]
  {
    (Struct length=9)
    {
      [CONTROL]
      {
        (String) NONE
      }
      [FLAGS]
      {
        (Integer) 1
      }
      [ID]
      {
        (String) LOWBAT
      }
      [MAX]
      {
        (Boolean) 1
      }
      [MIN]
      {
        (Boolean) 0
      }
      [OPERATIONS]
      {
        (Integer) 5
      }
      [TAB_ORDER]
      {
        (Integer) 1
      }
      [TYPE]
      {
        (String) BOOL
      }
      [UNIT]
      {
        (String)
      }
    }
  }
  [INSTALL_TEST]
  {
    (Struct length=8)
    {
      [FLAGS]
      {
        (Integer) 2
      }
      [ID]
      {
        (String) INSTALL_TEST
      }
      [MAX]
      {
        (Boolean) 1
      }
      [MIN]
      {
        (Boolean) 0
      }
      [OPERATIONS]
      {
        (Integer) 4
      }
      [TAB_ORDER]
      {
        (Integer) 2
      }
      [TYPE]
      {
        (String) ACTION
      }
      [UNIT]
      {
        (String)
      }
    }
  }
}
 

getParamsetId

Signatures

String getParamsetId(Integer peerId, Integer channel, String paramsetType)
String getParamsetId(Integer peerId, Integer channel, Integer remotePeerId, Integer remoteChannel)

Description

This method returns the ID of a device's or channel's parameter set as defined in the device's XML file.

Deprecated - For compatability only
String getParamset(String address, String paramsetType)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer.
12
channelIntegerThe channel to get the parameter set ID for.
1
remotePeerIdIntegerAn ID of a peer the peer is linked to. Used to get the ID of a link parameter set which is used to configure parameters of a direct link between two peers.
14
remoteChannelIntegerThe channel of peer "remotePeerId" the peer is linked to.
1
addressStringThe serial number and channel of the peer separated by colon.
JEQ0578372:1
paramsetTypeString"MASTER", "VALUES" or "LINK".
MASTER

Return Value

Returns a string with the ID of the parameter set as defined in the device's XML file.

Errors

CodeDescription
-2Device or channel unknown.
-3Parameter set is unknown.

Example Output

getParamsetId(12, 1, "VALUES")
(String) sc_ch_values
 

getPeerId

Signatures

Array getPeerId(Integer filterType, String filterValue)

Description

This method returns an array of all peer ID's matching the passed filter conditions.

Parameters

NameTypeDescriptionExample
filterTypeInteger
Filter TypeDescriptionFilter Value
1Filter by serial numberSerial number (e. g. JEQ0478327)
2Filter by physical addressPhysical address in decimal or hexadecimal format (e. g. 0x47a2b6 or 12748275)
3Filter by device type IDThe device type ID in decimal or hexadecimal format (e. g. 0x8b or 59)
4Filter by device type stringThe type string of the device (e. g. HM-CC-RT-DN)
5Filter by device nameThe name as returned by getDeviceInfo (e. g. 1st Floor Light). Partial values are allowed.
6All peers with pending configEmpty
7All unreachable peersEmpty
8All reachable peersEmpty
9All peers with low batteryEmpty
2
filterValueStringSee table above. Make sure the type is "String".
1

Return Value

Returns an array with the ID's of all matching peers.

Example Output

Example 1
getPeerId(1, "JEQ0098588")
(Array length=1)
{
  (Integer) 17
}
Example 2
getPeerId(2, 0x0000CF44)
(Array length=2)
{
  (Integer) 39
  (Integer) 52
}
 

getValue

Signatures

Variant getValue(Integer peerId, Integer channel, String parameterName)
Variant getValue(Integer peerId, Integer channel, String parameterName, Boolean requestFromDevice)
Variant getValue(Integer peerId, Integer channel, String parameterName, Boolean requestFromDevice, Boolean asynchronous)

Description

This method returns the value of a device variable.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to get the value for.
131
channelIntegerThe channel of the peer to get the value for.
1
parameterNameIntegerThe name of the variable as defined in the device's XML file.
1
requestFromDeviceBooleanWhen set to true Homegear tries to read the value from the device instead of returning the cached value. This is not possible for all devices.
true
asynchronousBooleanOnly relevant when requestFromDevice is true. When set to true the method returns immediately without waiting for the new value. The new value is sent as an event as soon as it is returned from the device.
true
addressstringThe serial number and channel of the device to get the value for (separated by colon).
JEQ0123456:1

Return Value

Returns the value of the parameter. The type of the value is defined in the device's XML file.

Errors

CodeDescription
-2Device or channel unknown.
-5Parameter is unknown.

Example Output

Example 1
getValue(131, 1, "STATE")
(Boolean) 1
Example 2
getValue(98, 4, "TEMPERATURE")
(Float) 22.1

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc '$hg->setValue(0, -1, "TEST", 5.5);'
homegear -e rc 'print_v($hg->getValue(0, -1, "TEST"));'
 

listDevices

Signatures

Array<DeviceDescription> listDevices()
Array<DeviceDescription> listDevices(Boolean channels, Array<String> fields)
Array<DeviceDescription> listDevices(Boolean channels, Array<String> fields, Integer familyId)

Description

This method returns an array of type DeviceDescription with one entry for each channel of each device paired to Homegear.

Parameters

NameTypeDescriptionExample
channelsBooleanWhen set to "false", only the description of the device without the channel descriptions is returned. This saves a lot of ressources. For compatability reasons, "channels" only works when "fields" is set, too.
false
fieldsArray<String>When fields is not empty, only the DeviceDescription elements defined in the array ("ID", "PHYSICAL_ADDRESS", ...) are returned. This also saves ressources.
[ "ID", "FAMILY", "TYPE_ID" ]
familyIdIntegerIf set only devices for this family are returned
4

Return Value

Returns an array of type DeviceDescription
 

listTeams

Signatures

Array<DeviceDescription> listTeams()

Description

This method returns an array of type DeviceDescription with one entry for each channel of each team in Homegear. Teams are a group of devices directly linked to each other (e. g. HomeMatic smoke detectors).

Parameters

This method has no parameters.

Return Value

Returns an array of type DeviceDescription

Example Output

listTeams()
(Array length=3)
{
  (Struct length=17)
  {
    [ADDRESS]
    {
      (String) *JEQ0170623
    }
    [CHANNELS]
    {
      (Array length=2)
      {
        (Integer) 0
        (Integer) 1
      }
    }
    [CHILDREN]
    {
      (Array length=2)
      {
        (String) *JEQ0170623:0
        (String) *JEQ0170623:1
      }
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [FIRMWARE]
    {
      (String) 0.0
    }
    [FLAGS]
    {
      (Integer) 9
    }
    [ID]
    {
      (Integer) 1073741826
    }
    [INTERFACE]
    {
      (String) VCENTRAL01
    }
    [PARAMSETS]
    {
      (Array length=1)
      {
        (String) MASTER
      }
    }
    [PARENT]
    {
      (String)
    }
    [PHYSICAL_ADDRESS]
    {
      (Integer) 1906477
    }
    [RF_ADDRESS]
    {
      (Integer) 1906477
    }
    [ROAMING]
    {
      (Integer) 0
    }
    [RX_MODE]
    {
      (Integer) 2
    }
    [TYPE]
    {
      (String) HM-Sec-SD-Team
    }
    [TYPE_ID]
    {
      (Integer) 66
    }
    [VERSION]
    {
      (Integer) 1
    }
  }
  (Struct length=15)
  {
    [ADDRESS]
    {
      (String) *JEQ0170623:0
    }
    [AES_ACTIVE]
    {
      (Integer) 0
    }
    [CHANNEL]
    {
      (Integer) 0
    }
    [DIRECTION]
    {
      (Integer) 0
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [FLAGS]
    {
      (Integer) 11
    }
    [ID]
    {
      (Integer) 1073741826
    }
    [INDEX]
    {
      (Integer) 0
    }
    [LINK_SOURCE_ROLES]
    {
      (String)
    }
    [LINK_TARGET_ROLES]
    {
      (String)
    }
    [PARAMSETS]
    {
      (Array length=2)
      {
        (String) MASTER
        (String) VALUES
      }
    }
    [PARENT]
    {
      (String) *JEQ0170623
    }
    [PARENT_TYPE]
    {
      (String) HM-Sec-SD-Team
    }
    [TYPE]
    {
      (String) MAINTENANCE
    }
    [VERSION]
    {
      (Integer) 1
    }
  }
  (Struct length=17)
  {
    [ADDRESS]
    {
      (String) *JEQ0170623:1
    }
    [AES_ACTIVE]
    {
      (Integer) 0
    }
    [CHANNEL]
    {
      (Integer) 1
    }
    [DIRECTION]
    {
      (Integer) 1
    }
    [FAMILY]
    {
      (Integer) 0
    }
    [FLAGS]
    {
      (Integer) 9
    }
    [ID]
    {
      (Integer) 1073741826
    }
    [INDEX]
    {
      (Integer) 1
    }
    [LINK_SOURCE_ROLES]
    {
      (String) KEYMATIC SWITCH WINMATIC
    }
    [LINK_TARGET_ROLES]
    {
      (String)
    }
    [PARAMSETS]
    {
      (Array length=3)
      {
        (String) MASTER
        (String) VALUES
        (String) LINK
      }
    }
    [PARENT]
    {
      (String) *JEQ0170623
    }
    [PARENT_TYPE]
    {
      (String) HM-Sec-SD-Team
    }
    [TEAM_CHANNELS]
    {
      (Array length=12)
      {
        (String) JEQ0736487:1
        (String) JEQ0317383:1
        (String) JEQ0172692:1
        (String) JEQ0170623:1
        (String) JEQ0269685:1
        (String) JEQ0317312:1
        (String) JEQ0351483:1
        (String) JEQ0172784:1
        (String) JEQ0351462:1
        (String) JEQ0172933:1
        (String) JEQ0174658:1
        (String) JEQ0351464:1
      }
    }
    [TEAM_TAG]
    {
      (String) smoke_detector
    }
    [TYPE]
    {
      (String) SMOKE_DETECTOR_TEAM
    }
    [VERSION]
    {
      (Integer) 1
    }
  }
}
 

putParamset

Signatures

(1) Void putParamset(Integer peerId, Integer channel, Paramset values)
(2) Void putParamset(Integer peerId, Integer channel, Integer remotePeerId, Integer remoteChannel, Paramset values)

Description

This method is used to set one or more static device configuration parameters. (1) is used to configure the device itself, (2) to configure links between two devices (if supported). In contrast to setValue() putParamset() can set multiple parameters with one call. This is necessary to avoid sending unnecessary packets and therefore cause unnecessary (RF) traffic in some device families.

Deprecated - For compatability only
Void putParamset(String address, String paramsetKey, Paramset values)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer.
12
channelIntegerThe channel to set the configuration parameters in.
1
remotePeerIdIntegerThe id of a remote peer linked to the peer. The function sets the corresponding link parameter set.
14
remoteChannelIntegerThe channel of a remote peer linked to the peer or "-1".
2
valuesStructA Struct containing the values to set with the name of the parameter as key. It does not have to contain all parameters of the parameter set, just the ones you want to set.
(Struct length=2)
{
  [EVENT_DELAYTIME]
  {
    (Float) 0
  }
  [TRANSMIT_TRY_MAX]
  {
    (Integer) 10
  }
}
addressStringThe serial number and channel of the peer separated by colon.
JEQ0578372:1
paramsetKeyStringMASTER for device's configuration parameters, VALUES to set multiple variables at once or the address of a linked peer to set LINK configuration parameters. Use getLinks() to find the IDs and channels a peer is linked to and getParamset() to see if there are any link parameters available.
MASTER

Return Value

Returns Void on success.

Errors

CodeDescription
-2Device or channel unknown.
-3Parameter set is unknown.

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc '$hg->putParamset(17, 0, array("BURST_RX" => false, BUTTON_LOCK => true));'
homegear -e rc '$hg->putParamset(31, 1, 34, 2, array("SHORT_ON_LEVEL" => 100, LONG_ON_LEVEL => 100));'
 

Signatures

Void removeLink(Integer senderId, Integer senderChannel, Integer receiverId, Integer receiverChannel)

Description

This method removes the direct link between two devices.

Deprecated - For compatability only
Void removeLink(String senderAddress, String receiverAddress)

Parameters

NameTypeDescriptionExample
senderIdIntegerThe ID of the sending peer (e.g. a remote)
12
senderChannelIntegerThe channel of the sending peer or "-1"
1
receiverIdIntegerThe ID of the receiving peer (e.g. a switch)
1
receiverChannelIntegerThe channel of the receiving peer or "-1"
1
senderAddressStringThe serial number and channel of the sending device (e.g. a remote), seperated by colon
JEQ0304693:7
receiverAddressStringThe serial number and channel of the receiving device (e.g. a switch), seperated by colon
JEQ0098488:1

Return Value

Returns Void on success

Errors

CodeDescription
-2At least one of the devices or channels is unknown.
-6The channels are not paired to each other.
 

setId

Signatures

Void setId(Integer currentPeerId, Integer newPeerId)

Description

This method changes the ID of a peer. This can be used for example to replace a device. The new ID has to be unused in order for this method to work.

Parameters

NameTypeDescriptionExample
currentPeerIdIntegerThe current ID of the peer
131
newPeerIdIntegerThe new ID of the peer
79

Return Value

Returns Void on success

Errors

CodeDescription
-2The device is unknown.
-100Current or new peer ID are invalid.
-101New peer ID is already in use.
 

setName

Signatures

Void setName(Integer peerId, String name)
Void setName(Integer peerId, Integer channel, String name)

Description

This method sets the name of a peer or channel. The name makes it easier to identify the peer.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer you want to set the name for
131
channelIntegerThe channel of the peer you want to set the name for (a channel of -1 sets the device's name). You can omit the channel when setting the name of the device.
1
nameStringThe name to assign to the device
Living Room - Light

Return Value

Returns Void on success

Errors

CodeDescription
-2Peer is unknown.
 

setTeam

Signatures

Void setTeam(Integer peerId, Integer channel)
Void setTeam(Integer peerId, Integer channel, Integer teamId, Integer teamChannel)

Description

This method adds a device to or removes it from a team. A team is a group of devices directly linked to each other. E. g. Sonos speakers or HomeMatic smoke detectors.

Deprecated - For compatability only
Void setTeam(String peerAddress, String teamAddress)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe id of the peer to add to the team.
131
channelIntegerThe channel of the peer to add to the team or "-1" if not applicable.
3
teamIdIntegerThe id of a the team. If teamID is "0" or not set, the peer is removed from the team.
132
teamChannelIntegerThe channel of the team to add the peer to or "-1" if not applicable.
true
peerAddressStringThe serial number and channel of the peer to add to the team (separated by a colon)
JEQ0123457:1
or
JEQ0123457
teamAddressStringThe serial number and channel of the team to add to the peer to (separated by a colon)
JEQ0123456:1
or
JEQ0123456

Return Value

Returns Void on success

Errors

CodeDescription
-2Peer/team or channel are unknown.
-6The channel or device doesn't support teams or the channels are incompatible to each other.
 

setValue

Signatures

Void setValue(Integer peerId, Integer channel, String variableName, Variant value [, Boolean wait = true])

Deprecated Signatures

Void setValue(String address, String variableName, Variant value [, Boolean wait = true])

Description

This method sets the value of a device variable. Note that it can't be used to set configuration parameters.

Parameters

peerId

The ID of the peer to set the value. Set peerId to 0 to set a system variable. When the system variable doesn't exist, it is created.

Example

31

channel

The channel of the peer to set the value. Set channel to -1 for system variables. When peerId is not 0 and channel is -1, variableName specifies a metadatum of the device. When the metadatum doesn't exist, it is created.

Example

3

variableName

The name of the variable to set.

Example

"SETPOINT_TEMPERATURE"

value

The new value of the variable. Please make sure the passed variable has the correct type (for languages with implied type conversion 21.0 for Float and not 21). A type conversion is implemented, but you shouldn't rely on it. When the type of the variable is Float or Integer, instead of passing the actual new value, you can also pass the following operations, followed without space by a number. The type of the value needs to be String:

  • +=<Number>
  • -=<Number>
  • *=<Number>
  • /=<Number>

In addtition ! toggles a Boolean value. This operation doesn't need to be followed by number.

You don't have to check for minimum or maximum values, as the new value will automatically be capped.

Example

31

Example 2

"+=0.5"

wait

Set to false if you don't want to wait for a response from the device. By default Homegear waits for a response when possible and returns an error when there is none. In some device families setting wait to false has no effect.

Return Values

Returns Void on success.

Exceptions

Code Description
-2 Peer or channel are unknown.
-5 Unknown parameter.
-6 Parameter is readonly.
-100 No answer from device.
-101 Device returned error.
 

Events

abortEventReset

Signatures

Void abortEventReset(String id)

Description

In the EventDescription you can define a reset method, which is executed some time after the event is triggered. To abort the reset timer and prevent the execution of this reset method, call abortEventReset().

Parameters

NameTypeDescriptionExample
idStringThe id of the event as defined by addEvent().
MyCustomEvent

Return Value

Returns Void on success

Errors

CodeDescription
-5Unknown event.
 

addEvent

Signatures

Void addEvent(EventDescription event)

Description

This method adds a triggered or timed event to Homegear. When an event is triggered, a XML-RPC method of your choice is executed (including runScript() for complex operations). Triggered events are checked when Homegear receives a packet from a device. They are raised e. g. when a device's parameter is changed. Events can also be triggered by system or metadata variable changes. Timed events can be triggered at a specific time point or recurrently (e. g. every two minutes).

Parameters

NameTypeDescriptionExample
eventEventDescriptionThe EventDescription defining the event.
(Struct length=12)
{
  [TYPE]
  {
    (Integer) 0
  }
  [ID]
  {
    (String) UG Treppenhaus Licht
  }
  [PEERID]
  {
    (Integer) 71
  }
  [PEERCHANNEL]
  {
    (Integer) 1
  }
  [VARIABLE]
  {
    (String) MOTION
  }
  [TRIGGER]
  {
    (Integer) 8
  }
  [TRIGGERVALUE]
  {
    (Boolean) 1
  }
  [EVENTMETHOD]
  {
    (String) setValue
  }
  [EVENTMETHODPARAMS]
  {
    (Array length=3)
    {
      (String) JEQ0101518:1
      (String) STATE
      (Boolean) 1
    }
  }
  [RESETAFTER]
  {
    (Struct length=5)
    {
      [FACTOR]
      {
        (Float) 2
      }
      [INITIALTIME]
      {
        (Integer) 45
      }
      [LIMIT]
      {
        (Integer) 180
      }
      [OPERATION]
      {
        (Integer) 3
      }
      [RESETAFTER]
      {
        (Integer) 240
      }
    }
  }
  [RESETMETHOD]
  {
    (String) setValue
  }
  [RESETMETHODPARAMS]
  {
    (Array length=3)
    {
      (String) JEQ0101518:1
      (String) STATE
      (Boolean) 0
    }
  }
}

Return Value

Returns Void on success

Errors

CodeDescription
-5Unknown event.
 

enableEvent

Signatures

Void enableEvent(String id, Boolean enable)

Description

This method enables or disables an event previously created with addEvent().

Parameters

NameTypeDescriptionExample
idStringThe id of the event as defined by addEvent().
MyCustomEvent
enableBooleantrue to enable and false to disable the event.
true

Return Value

Returns Void on success

Errors

CodeDescription
-5Unknown event.
 

getEvent

Signatures

EventDescription getEvent(String id)

Description

This method returns EventDescription of an event previously created with addEvent().

Parameters

NameTypeDescriptionExample
idStringThe id of the event as defined by addEvent().
MyCustomEvent

Return Value

Returns EventDescription on success

Errors

CodeDescription
-5Unknown event.
 

listEvents

Signatures

Array<EventDescription> listEvents()
Array<EventDescription> listEvents(Integer type)
Array<EventDescription> listEvents(Integer peerId, Integer channel)
Array<EventDescription> listEvents(Integer peerId, Integer channel, String variable)

Description

This method returns an Array of type EventDescription with all events previously created with addEvent().

Parameters

NameTypeDescriptionExample
typeInteger0 for triggered events or 1 for timed events. When specified listEvents returns only events of this event type.
0
peedIdIntegerThe id of the peer to get events for.
131
channelIntegerThe channel of the peer to get events for or -1 to return the events for all channels.
2
variableStringThe name of a peer's parameter inside channel. When specified listEvents returns only events for this parameter.
STATE

Return Value

Returns an Array of type EventDescription on success
 

removeEvent

Signatures

Void removeEvent(String id)

Description

This method removes an event previously created with addEvent().

Parameters

NameTypeDescriptionExample
idStringThe id of the event as defined by addEvent().
MyCustomEvent

Return Value

Returns Void on success

Errors

CodeDescription
-5Unknown event.
 

triggerEvent

Signatures

Void triggerEvent(String id)

Description

This method Manually triggers an event previously created with addEvent().

Parameters

NameTypeDescriptionExample
idStringThe id of the event as defined by addEvent().
MyCustomEvent

Return Value

Returns Void on success

Errors

CodeDescription
-5Unknown event.
 

Event Server

clientServerInitialized

Signatures

Boolean clientServerInitialized(String interfaceId)

Description

This method checks if an RPC client's RPC server is registered and connected to Homegear. You can register your RPC "event" server by calling init.

Parameters

NameTypeDescriptionExample
interfaceIdStringThe interface ID as specified in init
MyTotallyAwesomeHomegearClient

Return Value

Returns "True" if the RPC client's RPC server was successfully registered and is still connected. Otherwise, it returns "False".
 

init

Signatures

Void init(String interfaceId, Integer flags)

Description

This method enables sending of events over the current connection. After calling this method, Homegear's RPC client starts sending events and device updates (see the section on RPC client methods). It is not necessary to call init() for MQTT or WebSockets. For init() to work, the connected client must at least implement the method "system.listMethods".

Deprecated - For compatability only
Void init(String url, String interfaceId)
Void init(String url, String interfaceId, Integer flags)

Parameters

NameTypeDescriptionExample
interfaceIdStringThis is an arbitrary name for the interface. To unregister an event server, pass an empty string to interfaceId.
MyTotallyAwesomeHomegearClient
flagsIntegerThe following flags are available:
  • 0x01: keepAlive: Do not close the connection after each packet.
  • 0x02: binaryMode: Send RPC data in binary format. Equivalent to binary:// or binarys://.
  • 0x04: newFormat: (Recommended) Send device's ID in broadcast methods instead of the serial number and activates variable types ARRAY and STRUCT. This is recommended because serial numbers are not necessarily unique.
  • 0x08: subscribePeers: If this is set, Homegear will send events only for peers subscribed with subscribePeers() to the event server.
  • 0x10: jsonMode: Send RPC data in JSON format.
  • 0x20: dontSendNewDevices: Don't call listDevices() and newDevices() on client's event server after the call to init(). newDevices() is still being called when new devices are added.
  • 0x80: reconnectInfinitely: Try to reconnect to client's event server even if it is unreachable. With this flag, the connection is never removed by Homegear - except it is restarted, it can only be removed by calling init() with empty interfaceId.
3
urlStringWhen URL is specified, Homegear opens a new connection to the specified RPC server. The must include a prefix (e. g. http://) and the port. If you use binary://, RPC data is sent in binary format. If you pass https:// or binarys://, SSL is enabled.
binarys://192.168.0.5:3344
or
http://[fdef:3::1]:3344
or
https://myeventserver:3344

Return Value

Returns Void on success.

Errors

CodeDescription
-32602URL is invalid.
 

listClientServers

Signatures

ServerInfo listClientServers()
ServerInfo listClientServers(String interfaceId)

Description

This method returns an array of type ServerInfo with one entry for each RPC server registered with Homegear and does so by calling init.

Parameters

NameTypeDescriptionExample
interfaceIdStringThis is the interface ID of the RPC server as it was passed to init. If it is specified, only the ServerInfo for this server is returned.
MyTotallyAwesomeHomegearClient

Return Value

Returns an array of type ServerInfo

Errors

CodeDescription
-32602An interface ID was passed as an argument, but the server was not found.

Example Output

listClientServers()
(Array length=1)
{
  (Struct length=8)
  {
    [BINARY]
    {
      (Boolean) 0
    }
    [HOSTNAME]
    {
      (String) 127.0.0.1
    }
    [INTERFACE_ID]
    {
      (String) IPS
    }
    [IPADDRESS]
    {
      (String) 127.0.0.1
    }
    [KEEP_ALIVE]
    {
      (Boolean) 0
    }
    [USE_ID]
    {
      (Boolean) 0
    }
    [SUBSCRIBE_PEERS]
    {
      (Boolean) 0
    }
    [PORT]
    {
      (String) 5544
    }
    [SSL]
    {
      (Boolean) 0
    }
  }
}
 

subscribePeers

Signatures

Void subscribePeers(String eventServerId, Array<Integer> peerIds)

Description

This method is used to subscribe peer events after calling "init" with the "subscribePeers" flag set.

Parameters

NameTypeDescriptionExample
eventServerIdStringThis is either the url exactly as specified in "init" or the WebSocket client ID.
http://192.168.0.4:3344
peerIdsArray<Integer>This is an integer array containing the peer IDs to be subscribed. There is no check to see whether a peer ID is valid.
(Array length=3)
{
  (Integer) 13
  (Integer) 22
  (Integer) 31
}

Return Value

Returns Void on success

Errors

CodeDescription
-1Event server is unknown.
 

triggerRpcEvent

Signatures

Void triggerRpcEvent(String eventMethod, Array parameters)

Description

This method manually calls an RPC event method on all RPC event servers. Currently supported methods are "deleteDevices", "newDevices", and "updateDevice"

Parameters

NameTypeDescriptionExample
eventMethodStringThis is the method you want to call. The following methods are currently supported:
newDevices
parametersArrayThe parameters you want to pass to the event method
  • deleteDevices:Array<String> deviceAddresses, Array<Struct> deviceInfo
  • newDevices:Array<DeviceDescription> devices
  • deleteDevices:Integer peerId, integer channel, string address, integer flags
Please see the method's documentation for more information about the parameters.

Return Value

Returns Void on success

Errors

CodeDescription
-1Unknown method
 

unsubscribePeers

Signatures

Void unsubscribePeers(String eventServerId, Array<Integer> peerIds)

Description

This method is used to unsubscribe peer events after "subscribePeers" has been called.

Parameters

NameTypeDescriptionExample
eventServerIdStringThis is either the url exactly as specified in "init" or the WebSocket client ID.
http://192.168.0.4:3344
peerIdsArray<Integer>This is an integer array with the peer IDs you want to unsubscribe. There is no check for whether a peer ID is valid.
(Array length=3)
{
  (Integer) 13
  (Integer) 22
  (Integer) 31
}

Return Value

Returns Void on success

Errors

CodeDescription
-1Event server is unknown
 

Families

listFamilies

Signatures

Array<Struct> listFamilies()

Description

This method returns information about all available device families. Use this method to get the ID of a family if you have only the name or only the ID. You can also use this method to get the pairing methods supported by the family.

Parameters

This method has no parameters.

Return Value

Returns an array of structs containing information about all available device families. Each struct has the elements "ID" (integer), "NAME" (string) and "PAIRING_METHODS" (array).

Example Output

listFamilies()
(Array length=2)
{
  (Struct length=3)
  {
    [ID]
    {
      (Integer) 6
    }
    [NAME]
    {
      (String) Sonos
    }
    [PAIRING_METHODS]
    {
      (Array length=1)
      {
        (String) searchDevices
      }
    }
  }
  (Struct length=3)
  {
    [ID]
    {
      (Integer) 254
    }
    [NAME]
    {
      (String) Miscellaneous
    }
    [PAIRING_METHODS]
    {
      (Array length=1)
      {
        (String) createDevice
      }
    }
  }
}
 

Firmware Updates

getUpdateStatus

Signatures

Struct getUpdateStatus()

Description

This method returns the progress and result of one or more firmware updates.

Parameters

This method has no parameters.

Return Value

Returns a Struct with the following items:
NameTypeDescription
CURRENT_DEVICEIntegerThe id of the device that is currently being updated or -1 when no firmware updates are in progress.
CURRENT_DEVICE_PROGRESSIntegerThe progress in percent of the current device's update or -1 when no firmware updates are in progress.
DEVICE_COUNTIntegerThe overall number of devices to update or -1 when no firmware updates are in progress.
CURRENT_UPDATEIntegerThe number of the current update (from 1 to DEVICE_COUNT) or 0 when no firmware updates are in progress.
RESULTSStructThe update results. See below.
The Struct RESULTS contains all update results since Homegear started. The name of each element is the ID of the device. Each element again is a Struct with two elements: RESULT_CODE of type Integer and RESULT_STRING of type String. Possible result codes are:
RESULT_CODERESULT_STRING
0Update successful.
0Already up to date.
1Unknown error.
2No version file found.
3No firmware file found.
4Could not open firmware file.
5Firmware file has wrong format.
6Device did not respond to enter-bootloader packet.
7No update request received.
8Too many communication errors.
9No physical interface supports firmware updates.
 

updateFirmware

Signatures

(1) Void updateFirmware(Integer peerId)
(2) Void updateFirmware(Integer peerId, Boolean manually)
(3) Void updateFirmware(Array<Integer> peerIds)

Description

This method installs a firmware update on one or more devices. The firmware file has to be located in Homegear's firmware directory (default: /usr/share/homegear/firmware). You can use getDeviceDescription() to find out, if a firmware update is available for a device.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to update. Homegear will try to enable the device's update mode automatically. If this doesn't work or the update fails and the device only boots into update mode, set manually to true.
12
manuallyBooleanWhen set to true Homegear will wait for about 50 seconds for the device to enter the update mode and send an update request.
true
peerIdsArray<Integer>An Array of peer IDs to update. All provided devices will be updated sequentially. You can only provice IDs from one device family (e. g. HomeMatic BidCoS).
(Array length=4)
{
  (Integer) 12
  (Integer) 15
  (Integer) 18
  (Integer) 23
}

Return Value

Returns true on success for compatability reasons.

Errors

CodeDescription
-2Device or channel unknown or array of peers contains devices from multiple families.
-32500Homegear is already updating devices.
 

InfluxDB

influxdbCreateContinuousQuery

Signatures

Struct influxdbCreateContinuousQuery(String measurement)

Description

This method creates a continuous query for number measurements (Integer or Float) with Homegear's default settings to store aggregated data in the low resolution table. Use it when you manually created a measurement using influxdbWrite(). That only works if the field key is value. It is only available, when Homegear InfluxDB is installed and running.

Parameters

NameTypeDescriptionExample
measurementStringThe name of the measurement to create the continuous query for
myMeasurement

Return Value

Returns Void on success or Struct on InfluxDB error.

Errors

CodeDescription
-1InfluxDB error. The error struct contains a descriptive error message.
 

influxdbGetDatabase

Signatures

String influxdbGetDatabase()

Description

This method returns the name of the InfluxDB database used by Homegear. It is only available, when Homegear InfluxDB is installed and running.

Parameters

This method has no parameters.

Return Value

Returns the name of the database.
 

influxdbGetLoggedVariables

Signatures

Array influxdbGetLoggedVariables()
Array influxdbGetLoggedVariables(Integer peerId)

Description

This method returns all variables logged and known by Homegear InfluxDB. It is only available, when Homegear InfluxDB is installed and running.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to get logged variables for. If not specified, all logged variables are returned.
12

Return Value

Returns an Array of all logged variables. Each array element is a Struct with three elements:
  • PEERID (Integer): The ID of the logged variable's peer
  • CHANNEL (Integer): The channel of the logged variable's peer
  • VARIABLE (String): The name of the logged variable

Example Output

influxdbGetLoggedVariables(31)
(Array length=1)
{
  (Struct length=3)
  {
    [CHANNEL]
    {
      (Integer) 10
    }
    [PEERID]
    {
      (Integer) 31
    }
    [VARIABLE]
    {
      (String) TEMPERATURE
    }
  }
}
 

influxdbQuery

Signatures

Struct influxdbQuery(Boolean httpPost, String query)
Struct influxdbQuery(Boolean httpPost, String query, Struct additionalHttpQueryParameters)

Description

This method executes an InfluxDB query in the database connected to Homegear InfluxDB. It is only available, when Homegear InfluxDB is installed and running.

Parameters

NameTypeDescriptionExample
httpPostBooleanWhen set to false HTTP GET is used (for SELECT [without INTO] and SHOW), when set to true HTTP POST is used (for everything else).
false
queryStringThe query to execute.
SHOW MEASUREMENTS
additionalHttpQueryParametersStructThese parameters are appended to the HTTP query parameters.
{"epoch": "ms"}

Return Value

Returns a Struct with the result.

Errors

CodeDescription
-1InfluxDB error. The error struct contains a descriptive error message.

Example Output

influxdbQuery(false, "SHOW MEASUREMENTS")
(Struct length=1)
{
  [results]
  {
    (Array length=1)
    {
      (Struct length=2)
      {
        [series]
        {
          (Array length=1)
          {
            (Struct length=3)
            {
              [columns]
              {
                (Array length=1)
                {
                  (String) name
                }
              }
              [name]
              {
                (String) measurements
              }
              [values]
              {
                (Array length=19)
                {
                  (Array length=1)
                  {
                    (String) history_19_10_TEMPERATURE
                  }
                  (Array length=1)
                  {
                    (String) history_30_10_TEMPERATURE
                  }
                  .
                  .
                  .
                }
              }
            }
          }
        }
        [statement_id]
        {
          (Integer) 0
        }
      }
    }
  }
}

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->influxdbQuery(false, "SHOW MEASUREMENTS"));'
 

influxdbSetLogging

Signatures

Void influxdbSetLogging(Integer peerId, Integer channel, String variable, Variant initialValue, Boolean enableLogging)

Description

This method enables automatic logging for a specific device or system variable in InfluxDB. It is only available, when Homegear InfluxDB is installed and running. There is no need to call influxdbWrite.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer containing the variable to log. For system variables use 0.
12
channelIntegerThe channel containing the variable to log. For metadata use -1.
2
variableStringThe variable to log.
TEMPERATURE
initialValueVariantMandatory when enableLogging is true. Ignored when it is false. The initial value to write into the database. You can for example pass the output of getValue. initialValue is used to determine the type of the variable.
21.2
enableLoggingBooleantrue enables logging of variable value changes, false disables it and deletes all previously logged entries from the database.
true

Return Value

Returns Void on success.

Errors

CodeDescription
-1InfluxDB error. The error struct contains a descriptive error message.

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->setSystemVariable("TEST", 12.3));'
homegear -e rc 'print_v($hg->influxdbSetLogging(0, -1, "TEST", $hg->getSystemVariable("TEST"), true));'
 

influxdbWrite

Signatures

Struct influxdbWrite(Boolean useLowResRetentionPolicy, String data)

Description

This method executes a manual InfluxDB write in the database connected to Homegear InfluxDB. This can be used to log your own values e. g. from within your scripts or Node-BLUE. It is only available, when Homegear InfluxDB is installed and running. When logging has been enabled for a variable using influxdbSetLogging there is no need to call influxdbWrite.

Parameters

NameTypeDescriptionExample
useLowResRetentionPolicyBooleanWhen set to true the data is written to the low resolution retention policy. When set to false the high resolution retention policy is used.
false
dataStringThe data in InfluxDB's Line Protocol format.
myMeasurement value=12.3

Return Value

Returns Void on success or Struct on InfluxDB error.

Errors

CodeDescription
-1InfluxDB error. The error struct contains a descriptive error message.

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc 'print_v($hg->influxdbWrite(false, "myMeasurement value=12.3"));'
 

Metadata

deleteMetadata

Signatures

Void deleteMetadata(Integer peerId)
Void deleteMetadata(Integer peerId, String dataId)

Description

This method deletes previously stored metadata.

Deprecated - For compatability only
Void deleteMetadata(String address)
Void deleteMetadata(String address, String dataId)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer for which the metadata is stored.
131
addressStringThe serial number and channel of the device for which the metadata is stored (separated by colon)
JEQ0123456:1
or
JEQ0123456
dataIdStringThe dataId as defined in setMetadata
myData

Return Value

Returns Void on success

Errors

CodeDescription
-2Peer is unknown.
-32602dataId is longer than 250 characters.
 

getAllMetadata

Signatures

Struct getAllMetadata(Integer peerId)

Description

This method returns all the metadata of one peer.

Deprecated - For compatability only
Struct getAllMetadata(String address)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer for which you want to get metadata
131
addressStringThe serial number and channel of the device for which you want to get metadata (separated by a colon)
JEQ0123456:1
or
JEQ0123456

Return Value

This returns a struct with one element for each dataId containing the previously stored value. The name of the element is the dataId.

Errors

CodeDescription
-2Peer is unknown.
-1No metadata found.

Example Output

getAllMetadata(12)
(Struct length=1)
{
  [NAME]
  {
    (String) My HM-CC-TC
  }
  [CUSTOMDATA]
  {
    (Float) 21.6
  }
}
 

getMetadata

Signatures

Variant getMetadata(Integer peerId, String dataId)

Description

This method returns metadata that was previously stored with setMetadata.

Deprecated - For compatability only
Variant getMetadata(String address, String dataId)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer for which you want to get the metadata
131
addressStringThe serial number and channel of the device for which you want to get the metadata (separated by a colon)
JEQ0123456:1
or
JEQ0123456
dataIdStringThe data ID as defined in setMetadata
myData

Return Value

Returns the stored element

Errors

CodeDescription
-2Peer is unknown.
-1No metadata found.
-32602dataId is longer than 250 characters.

Example Output

getMetadata(12, "TestData")
(Float) 21.6
 

setMetadata

Signatures

Void setMetadata(Integer peerId, String dataId)
Void setMetadata(Integer peerId, String dataId, Variant value)

Description

This method can be used to store metadata for devices in Homegear's database. You can retrieve this metadata later by calling getMetadata.

Deprecated - For compatability only
Void setMetadata(String address, String dataId, Variant value)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer for which you want to store metadata
131
addressStringThe serial number and channel of the device for which you want to store metadata (separated by a colon)
JEQ0123456:1
or
JEQ0123456
dataIdStringA name of your choice
"myData"
valueVariantThe value you want to store. When ommited the type of the variable is set to Void.
43

Return Value

Returns Void on success

Errors

CodeDescription
-2Peer is unknown.
-32700Data could not be encoded to binary format.
-32602dataId is longer than 250 characters.
-32500The limit of 1 million metadata entries has been reached.
 

Node-BLUE

getNodeVariable

Signatures

Variant getNodeVariable(String nodeId, String variableName, Variant value)

Description

This method calls getNodeVariable in the specified node. For this to work, the node must implement getNodeVariable. The variable names and values are node-specific.

Parameters

nodeId

The node to call getNodeVariable in.

variableName

The variable to get.

Return Values

Returns the value of the variable variableName on success.

Exceptions

This method only throws default exceptions. The node is allowed to implement it's own exceptions though.

Examples

homegear -e rc '$hg->getNodeVariable("fbda37e9.6b2ee8", "my-variable");'
 

setNodeVariable

Signatures

Void setNodeVariable(String nodeId, String variableName, Variant value)

Description

This method calls setNodeVariable in the specified node. For this to work, the node must implement setNodeVariable. The variable names and values are node-specific.

Parameters

nodeId

The node to call setNodeVariable in.

variableName

The variable to set.

value

The value to set the variable variableName to.

Return Values

Returns Void on success:

Exceptions

This method only throws default exceptions.

Examples

homegear -e rc '$hg->setNodeVariable("fbda37e9.6b2ee8", "my-variable", true);'
 

Pairing

addDevice

Signatures

DeviceDescription addDevice(String serialNumber)
DeviceDescription addDevice(Integer familyId, String serialNumber)

Description

This method pairs a device by its serial number, but this does not work for all devices.

Parameters

NameTypeDescriptionExample
serialNumberStringThe serial number of the device to be paired
JEQ0095288
familyIdIntegerID of the family you want to add the device to; if not specified, "addDevice" is executed for all device families that support it.
1

Return Value

Returns the device description of the newly paired device if the pairing was successful

Errors

CodeDescription
-1Pairing was unsuccessful.

Example Output

addDevice(JEQ0098488)
(Struct length=11)
{
  [ADDRESS]
  {
    (String) JEQ0098488
  }
  [CHILDREN]
  {
    (Array length=2)
    {
      (String) JEQ0098488:0
      (String) JEQ0098488:1
    }
  }
  [FIRMWARE]
  {
    (String) 2.1
  }
  [FLAGS]
  {
    (Integer) 1
  }
  [INTERFACE]
  {
    (String) VCENTRAL01
  }
  [PARAMSETS]
  {
    (Array length=1)
    {
      (String) MASTER
    }
  }
  [PARENT]
  {
    (String)
  }
  [RF_ADDRESS]
  {
    (String) 1794452
  }
  [ROAMING]
  {
    (Integer) 0
  }
  [TYPE]
  {
    (String) HM-LC-Sw1PBU-FM
  }
  [VERSION]
  {
    (Integer) 2
  }
}
 

createDevice

Signatures

(1) Integer createDevice(Integer familyId, Integer deviceType, String serialNumber, Integer address, Integer firmwareVersion)
(2) Integer createDevice(Integer familyId, Integer deviceType, String serialNumber, Integer address, Integer firmwareVersion, String interfaceId)
(3) Integer createDevice(String code)

Description

This method manually creates a new device. It is not supported by all device families, and it is also not supported for all devices. createDevice can be used to create virtual devices in the family "Miscellaneous".

Parameters

NameTypeDescriptionExample
familyIdIntegerThis is the ID of the family you want to create the device in. See: listFamilies.
1
deviceTypeIntegerThe type ID of the device as specified in the device's XML file
483
serialNumberStringThe serial number of the new device
MY_DEVICE1
addressIntegerThis is the physical address of the new device. Depending on the device family, this parameter might be optional. If it is not needed, set it to "-1".
9874387
firmwareVersionIntegerThis is the firmware version of the new device. Depending on the device family, this parameter might be optional. If the firmware version is "1.2", set this variable to 0x12 = 18. If it is not needed, set it to "-1".
18
interfaceIdStringThe ID of the interface as defined in the family configuration file with which you want to associate the newly created device
My-Interface
codeStringA code containing all information to create or pair the device
30S0000050E71BB+1P004000000009+10Z00+11Z23981AB3+S---

Return Value

Returns the ID of the new device on success.

Errors

CodeDescription
-2The device family is unknown or unavailable ((1) and (2)). Device creation or pairing is taking place in background i. e. for wake up devices ((3)).
-5A device with this serial number or address already exists ((1), (2) and (3)).
-6This device type is unknown or no matching device could be found ((1), (2) and (3)).
-32601Method not implemented by the device family
 

getInstallMode

Signatures

Integer getInstallMode()
Integer getInstallMode(Integer familyId)

Description

This method returns the remaining amount of time the central will be in pairing mode.

Parameters

NameTypeDescriptionExample
familyIdIntegerThis is the ID of the family for which you want to get the remaining time in pairing mode. If not specified, the remaining time in pairing mode of the first central for which pairing mode enabled is returned.
1

Return Value

This returns the remaining time in pairing mode (in seconds or "0") when the central is not in pairing mode.
 

getPairingInfo

Signatures

Struct; getPairingInfo(Integer familyId)

Description

This method returns all information necessary to add communication modules and to pair devices.

Parameters

NameTypeDescriptionExample
familyIdIntegerThe ID of the family for which you want to get the supported pairing methods
1

Return Value

Returns the pairing information as a struct.

Example Output

getPairingInfo(0)
Array
(
    [0] => addDevice
    [1] => setInstallMode
)
 

searchDevices

Signatures

Integer searchDevices()
Integer searchDevices(Integer familyId)
Integer searchDevices(Integer familyId, String interfaceId)

Description

When you use this method, Homegear searches for new devices in all device families that support the method.

Parameters

NameTypeDescriptionExample
familyIdIntegerThis is the ID of the family that you want to search for devices.
1
interfaceIdStringLimit the search to this interface. Does not work with all device families.
My-Interface

Return Value

Returns the number of devices that the method found or -2 if the search is run in background. If the latter is the case newly found devices are broadcast by newDevices().
 

setInstallMode

Signatures

Void setInstallMode(Boolean on)
Void setInstallMode(Boolean on, Integer duration)
Void setInstallMode(Integer familyId, Boolean on)
Void setInstallMode(Integer familyId, Boolean on, Struct metadata)
Void setInstallMode(Integer familyId, Boolean on, Integer duration)
Void setInstallMode(Integer familyId, Boolean on, Integer duration, Struct metadata)

Description

This method enables or disables pairing mode for all device families if it is supported by the device family.

Parameters

NameTypeDescriptionExample
onBooleanWhen this is true, pairing mode is enabled. Otherwise, pairing mode is disabled.
1
durationIntegerThis is the duration in seconds that the central should remain in pairing mode. The minimum duration is 5 seconds, and the maximum duration is 3600 seconds. The default duration is 60 seconds.
120
familyIdIntegerThis is the ID of the family for which you want to enable pairing mode. If it is not specified, pairing mode will be enabled for all device families.
1
metadataStructFamily specific metadata.

Return Value

Returns Void on success
 

Physical Interfaces

listBidcosInterfaces

Signatures

Array<Struct> listBidcosInterfaces()

Description

This method exists only for reasons of backward compatibility with the CCU and has no real function.

Parameters

This method has no parameters.

Return Value

It returns an array with one element. This element is a struct with four fields:
  • ADDRESS (String): The serial number of your central device
  • DESCRIPTION (String): Always: "Homegear default interface"
  • CONNECTED (Boolean): State of the RF device; if it is false, the RF device is not working.
  • DEFAULT (Boolean): Always true

Example Output

listBidcosInterfaces()
listBidcosInterfaces()
 
(Array length=1)
{
  (Struct length=4)
  {
    [ADDRESS]
    {
      (String) VCENTRAL01
    }
    [DESCRIPTION]
    {
      (String) Homegear default interface
    }
    [CONNECTED]
    {
      (Boolean) 1
    }
    [DEFAULT]
    {
      (Boolean) 1
    }
  }
}
 

listInterfaces

Signatures

Array<InterfaceDescription> listInterfaces()
Array<InterfaceDescription> listInterfaces(Integer familyId)

Description

This method returns a list of all physical interfaces. It can be used to determine if an interface is available.

Parameters

NameTypeDescriptionExample
familyIdIntegerThe ID of the family for which you want to get interfaces
4

Return Value

Returns an array of type InterfaceDescription

Example Output

listInterfaces()
(Array length=2)
{
  (Struct length=7)
  {
    [ID]
    {
      (String) MyInterface
    }
    [CONNECTED]
    {
      (Boolean) 1
    }
    [DEFAULT]
    {
      (Boolean) 1
    }
    [FAMILYID]
    {
      (Integer) 0
    }
    [LASTPACKETRECEIVED]
    {
      (Integer) 1393069264
    }
    [LASTPACKETSENT]
    {
      (Integer) 1393069364
    }
    [PHYSICALADDRESS]
    {
      (Integer) 16581789
    }
    [TYPE]
    {
      (String) cc1100
    }
  }
  (Struct length=7)
  {
    [ID]
    {
      (String) MySecondInterface
    }
    [CONNECTED]
    {
      (Boolean) 1
    }
    [DEFAULT]
    {
      (Boolean) 1
    }
    [FAMILYID]
    {
      (Integer) 1
    }
    [LASTPACKETRECEIVED]
    {
      (Integer) 1393069243
    }
    [LASTPACKETSENT]
    {
      (Integer) 1393069243
    }
    [PHYSICALADDRESS]
    {
      (Integer) 1
    }
    [TYPE]
    {
      (String) rs485
    }
  }
}
 

setInterface

Signatures

Void setInterface(Integer peerId, String interfaceId)

Description

This method sets the physical interface that Homegear is to use to communicate with a peer.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer you want to set the interface for
131
interfaceIdStringThis is the ID of the physical interface as defined in the family interface settings. If it is empty, the physical interface is reset to the default interface.
MyInterface

Return Value

Returns Void on success

Errors

CodeDescription
-2Peer is unknown.
-5Interface is unknown.
-104ROAMING is enabled. You need to disable it before you can manually choose an interface.
 

Roles

addRoleToVariable

Signatures

Boolean addRoleToVariable(Integer peerId, Integer channel, String variableName, Integer roleId [, Integer direction = 2 [, Boolean invert = false [, Struct scale = {}]]])

Description

This method adds a role to a variable.

Parameters

peerId

The ID of the peer to add the role to. Set to 0 to add a role to a system variable.

Example

12

channel

The channel of the peer to add the role to. Set to -1 to add a role to a system or metadata variable.

Example

1

variableName

The variable of the peer to add the role to.

Example

"TEMPERATURE"

roleId

The ID of the role as returned by createRole() or getRoles().

Example

201003

direction

Specifies, whether the variable is an input or output variable - or both. This is relevant, when there is one variable for input and another variable for output. Specifying direction you can assign the same role to both of them.

Value Description
0 The variable is an input variable (i. e. the value is coming from the device). Readonly variables are always input variables.
1 The variable is an output variable (i. e. the value is sent to the device). Writeonly variables are always output variables.
2 This is the default. The variable is an input and output variable.

invert

Invert the value of the variable. This makes the variable look like the inverted value everywhere it can be accessed.

scale

Scales the logical value of the variable. This makes the variable look like the scaled version everywhere it can be accessed. Scale is a Struct with the following entries:

Key Optional Description
valueMin yes The minimum value of the unscaled variable. If omitted Homegear uses the minimum value from the device description file.
valueMax yes The maximum value of the unscaled variable. If omitted Homegear uses the maximum value from the device description file.
scaleMin no The minimum value of the scale range the variable should be scaled to.
scaleMax no The maximum value of the scale range the variable should be scaled to.

Example

{
    "valueMin": 0,
    "valueMax": 255,
    "scaleMin": 0,
    "scaleMax": 100
}

This will scale the device value with a value range between 0 and 255 to a value between 0 and 100.

Return Values

Returns true on success and false if something went wrong (e. g. unknown channel).

Exceptions

Code Description
-1 Role unknown.
-2 Variable is unknown.
 

aggregateRoles

Signatures

Struct aggregateRoles(Integer aggregationType, Integer roleId, Struct aggregationParameters [, Integer roomId = 0 [, Boolean visualizedVariablesOnly = false]])
Struct aggregateRoles(Integer aggregationType, Array<Integer> roleIds, Struct aggregationParameters [, Integer roomId = 0 [, Boolean visualizedVariablesOnly = false]])

Description

This method aggregates values of variables with specific roles.

Parameters

NameTypeDescriptionExample
aggregationTypeStructThe type of aggregation to perform. Available aggregations:
  • 1: countTrue - Evaluates the variables to true and false (all variable types are evaluated) and counts the result.
  • 2: countDistinct - Counts all distinct number values.
  • 3: countMinimum - Counts all variables having their minimum value.
  • 4: countMaximum - Counts all variables having their maximum value.
  • 5: countBelowThreshold - Counts all variables below a threshold. The threshold value needs to be set in aggregationParameters to the key threshold.
  • 4: countAboveThreshold - Counts all variables above a threshold. The threshold value needs to be set in aggregationParameters to the key threshold.
3
roleIdIntegerThe role ID to get the variables to aggregate for.
101001
roleIdsArrayMultiple role IDs to get the variables to aggregate for.
[101001, 101002, 101003]
aggregationParametersStructAdditional aggregation parameters. Required for some aggregations. See aggregationType if additional parameters are required.
{"threshold": 20}
roomIdIntegerIf specified only variables within this room are aggregated.
5
visualizedVariablesOnlyBooleanOnly count variables that are used in UI elements.
true

Return Value

Returns the aggregated values as a Struct.
 

createRole

Signatures

Integer createRole(Struct translations)
Integer createRole(Struct translations, Struct metadata)

Description

This method creates a new role.

Parameters

NameTypeDescriptionExample
translationsStructThe name of the role in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the role names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) Light
  }
  [de-DE]
  {
    (String) Licht
  }
}
metadataStructArbitrary metadata.

Return Value

Returns the ID of the new role.
 

deleteRole

Signatures

Void deleteRole(Integer roleId)

Description

This method deletes a role.

Parameters

NameTypeDescriptionExample
roleIdIntegerThe ID of the role as returned by createRole() or getRoles().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Role unknown.
 

getRoleMetadata

Signatures

Struct getRoleMetadata(Integer roleId)

Description

This method returns the metadata of an existing role.

Parameters

NameTypeDescriptionExample
roleIdIntegerThe ID of the role as returned by createRole() or getRoles().
3

Return Value

Returns the role's metadata on success.

Errors

CodeDescription
-1Role unknown.
 

getRoles

Signatures

Array<Struct> getRoles()
Array<Struct> getRoles(String languageCode)

Description

This method returns all role IDs, one or all translations and the role metadata.

Parameters

NameTypeDescriptionExample
languageCodeStringA lower case ISO 639-1 language and upper case ISO 3166-1 alpha-2 country code seperated by a dash.
en-GB

Return Value

Returns an Array<Struct> with all roles on success. When languageCode is specified each Array element is a Struct with three entries: The ID of type Integer, NAME of type String and METADATA of type Struct. If the specified translation is unknown an empty String is returned for NAME. When languageCode is not specified each Array element is also a Struct with three entries: The ID of type Integer, TRANSLATIONS of type Struct with the language code as key and the name as value and METADATA of type Struct.
 

getVariablesInRole

Signatures

Struct getVariablesInRole(Integer roleId)
Struct getVariablesInRole(Integer roleId, Integer peerId)

Description

This method returns all variables of a role.

Parameters

NameTypeDescriptionExample
roleIdIntegerThe ID of the role as returned by createRole() or getRoles().
3
peerIdIntegerOnly return variables for this peer ID.
12

Return Value

Returns variables assigned to the specified role. The root element is a Struct with all peer IDs as key and all channels as value (Struct). The channels again have the variables as value (Array<String>).

Errors

CodeDescription
-1Role unknown.
 

removeRoleFromVariable

Signatures

Boolean removeRoleFromVariable(Integer peerId, Integer channel, String variableName, Integer roleId)

Description

This method removes a role from a variable.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove the role from.
12
channelIntegerThe channel of the peer to remove the role from.
1
variableNameStringThe variable of the peer to remove the role from.
TEMPERATURE
roleIdIntegerThe ID of the role as returned by createRole() or getRoles().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).
 

setRoleMetadata

Signatures

Void setRoleMetadata(Integer roleId, Struct metadata)

Description

This method updates the translations of an existing role.

Parameters

NameTypeDescriptionExample
roleIdIntegerThe ID of the role as returned by createRole() or getRoles().
3
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Role unknown.
 

updateRole

Signatures

Void updateRole(Integer roleId, Struct translations)
Void updateRole(Integer roleId, Struct translations, Struct metadata)

Description

This method updates the translations and metadata of an existing role.

Parameters

NameTypeDescriptionExample
roleIdIntegerThe ID of the role as returned by createRole() or getRoles().
3
translationsStructThe name of the role in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the role names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) Light
  }
  [de-DE]
  {
    (String) Licht
  }
}
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Role unknown.
 

Rooms and Categories

addBuildingPartToBuilding

Signatures

Boolean addBuildingPartToBuilding(Integer buildingId, Integer buildingPartId)

Description

This method assigns a building part to a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

buildingPartId

The ID of the building part as returned by createBuildingPart() or getBuildingParts().

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building.
-2 Unknown building part.
 

addCategoryToChannel

Signatures

Boolean addCategoryToChannel(Integer peerId, Integer channel, Integer categoryId)

Description

This method adds a category to a channel.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to add the category to.
12
channelIntegerThe channel of the peer to add the category to. When passing -1 the call is equivalent to addCategoryToDevice().
1
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).

Errors

CodeDescription
-1Unknown category.
-2Unknown device.
 

addCategoryToDevice

Signatures

Boolean addCategoryToDevice(Integer peerId, Integer categoryId)

Description

This method adds a category to a device.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to add the category to.
12
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).

Errors

CodeDescription
-1Unknown category.
-2Unknown device.
 

addCategoryToSystemVariable

Signatures

Void addCategoryToSystemVariable(String systemVariableName, Integer categoryId)

Description

This method adds a category to a system variable.

Parameters

NameTypeDescriptionExample
systemVariableNameStringThe name of the system variable to add the category to.
12
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Unknown room.
-5Unknown variable.
 

addCategoryToVariable

Signatures

Boolean addCategoryToVariable(Integer peerId, Integer channel, String variableName, Integer categoryId)

Description

This method adds a category to a variable.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to add the category to.
12
channelIntegerThe channel of the peer to add the category to.
1
variableNameStringThe variable of the peer to add the category to.
TEMPERATURE
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).

Errors

CodeDescription
-1Unknown category.
-2Unknown device.
 

addChannelToRoom

Signatures

Boolean addChannelToRoom(Integer peerId, Integer channel, Integer roomId)

Description

This method assigns a channel to a room. If a room already is assigned to the channel this assignment is overwritten.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to assign to the room.
12
channelIntegerThe channel of the peer to assign to the room. When passing -1 the call is equivalent to addDeviceToRoom().
1
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns true on success and false on errors (e. g. unknown channel).

Errors

CodeDescription
-1Unknown room.
-2Unknown device.
 

addDeviceToRoom

Signatures

Boolean addDeviceToRoom(Integer peerId, Integer roomId)

Description

This method assigns a device to a room. If a room already is assigned to the device this assignment is overwritten.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to assign to the room.
12
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns true on success and false on errors (e. g. unknown channel).

Errors

CodeDescription
-1Unknown room.
-2Unknown device.
 

addRoomToStory

Signatures

Boolean addRoomToStory(Integer storyId, Integer roomId)

Description

This method assigns a room to a story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
12
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Unknown story.
-2Unknown room.
 

addStoryToBuilding

Signatures

Boolean addStoryToBuilding(Integer buildingId, Integer storyId)

Description

This method assigns a story to a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

storyId

The ID of the story as returned by createStory() or getStories().

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building.
-2 Unknown story.
 

addSystemVariableToRoom

Signatures

Void addSystemVariableToRoom(String systemVariableName, Integer roomId)

Description

This method assigns a system variable to a room. If a room already is assigned to the system variable this assignment is overwritten.

Parameters

NameTypeDescriptionExample
systemVariableNameStringThe name of the system variable to add to the room.
12
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Unknown room.
-5Unknown variable.
 

addVariableToRoom

Signatures

Boolean addVariableToRoom(Integer peerId, Integer channel, String variableName, Integer roomId)

Description

This method assigns a variable to a room. If a room already is assigned to the variable this assignment is overwritten.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to assign to the room.
12
channelIntegerThe channel of the peer to assign to the room.
1
variableNameStringThe variable of the peer to assign to the room.
TEMPERATURE
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns true on success and false on errors (e. g. unknown channel).

Errors

CodeDescription
-1Unknown room.
-2Unknown device.
 

createBuilding

Signatures

Integer createBuilding(Struct translations, Struct metadata = {})

Description

This method creates a new building.

Parameters

translations

The name of the building in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the building names in the different languages.

Example

{
    "en-US": "Building 1",
    "de-DE": "Gebäude 1"
}

metadata

Arbitrary metadata.

Return Values

Returns the ID of the new building on success.

 

createBuildingPart

Signatures

Integer createBuildingPart(Struct translations, Struct metadata = {})

Description

This method creates a new building part.

Parameters

translations

The name of the building part in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the building part names in the different languages.

Example

{
    "en-US": "Apartment 1",
    "de-DE": "Wohnung 1"
}

metadata

Arbitrary metadata.

Return Values

Returns the ID of the new building part on success.

 

createCategory

Signatures

Integer createCategory(Struct translations)
Integer createCategory(Struct translations, Struct metadata)

Description

This method creates a new category.

Parameters

NameTypeDescriptionExample
translationsStructThe name of the category in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the category names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) Light
  }
  [de-DE]
  {
    (String) Licht
  }
}
metadataStructArbitrary metadata.

Return Value

Returns the ID of the new category.
 

createRoom

Signatures

Integer createRoom(Struct translations)
Integer createRoom(Struct translations, Struct metadata)

Description

This method creates a new room.

Parameters

NameTypeDescriptionExample
translationsStructThe name of the room in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the room names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) Living room
  }
  [de-DE]
  {
    (String) Wohnzimmer
  }
}
metadataStructArbitrary metadata.

Return Value

Returns the ID of the new room.
 

createStory

Signatures

Integer createStory(Struct translations)
Integer createStory(Struct translations, Struct metadata)

Description

This method creates a new story.

Parameters

NameTypeDescriptionExample
translationsStructThe name of the story in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the story names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) 1st Floor
  }
  [de-DE]
  {
    (String) 1. Obergeschoss
  }
}
metadataStructArbitrary metadata.

Return Value

Returns the ID of the new story.
 

deleteBuilding

Signatures

Void deleteBuilding(Integer buildingId)

Description

This method deletes a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building.
 

deleteBuildingPart

Signatures

Void deleteBuildingPart(Integer buildingId)

Description

This method deletes a building part.

Parameters

buildingPartId

The ID of the building part as returned by createBuildingPart() or getBuildingParts().

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building part.
 

deleteCategory

Signatures

Void deleteCategory(Integer categoryId)

Description

This method deletes a category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Category unknown.
 

deleteRoom

Signatures

Void deleteRoom(Integer roomId)

Description

This method deletes a room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Room unknown.
 

deleteStory

Signatures

Void deleteStory(Integer storyId)

Description

This method deletes a story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Story unknown.
 

getBuildingMetadata

Signatures

Struct getBuildingMetadata(Integer buildingId)

Description

This method returns the metadata of an existing building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

Return Values

Returns the buildings's metadata on success.

Exceptions

Code Description
-1 Unknown building.
 

getBuildingPartMetadata

Signatures

Struct getBuildingPartMetadata(Integer buildingPartId)

Description

This method returns the metadata of an existing building part.

Parameters

buildingPartId

The ID of the building part as returned by createBuildingPart() or getBuildingParts().

Return Values

Returns the buildings part's metadata on success.

Exceptions

Code Description
-1 Unknown building part.
 

getBuildingParts

Signatures

Array<Struct> getBuildingParts(String languageCode = "")

Description

This method returns all building part IDs, one or all translations and the building part metadata.

Parameters

languageCode

An optional lower case ISO 639-1 language and upper case ISO 3166-1 alpha-2 country code seperated by a dash. If specified, only this translation is returned.

Example

"en-US"

Return Values

Returns an Array<Struct> with all building parts on success. When languageCode is specified, each Array element is a Struct with three entries:

Key Type
ID Integer
NAME String
METADATA Struct

The name will be resolved in the following order:

  1. languageCode
  2. en-US
  3. First available language
  4. Empty string

When languageCode is not specified, each Array element is also a Struct with three entries:

Key Type
ID Integer
TRANSLATIONS Struct
METADATA Struct

The key of TRANSLATIONS is the language code and the value the translation.

 

getBuildingPartsInBuilding

Signatures

Array<Integer> getBuildingPartsInBuilding(Integer buildingId)

Description

This method returns all building parts of a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

Return Values

Returns an Array<Integer> with all building part IDs assigned to the specified building.

Exceptions

Code Description
-1 Unknown building.
 

getBuildings

Signatures

Array<Struct> getBuildings(String languageCode = "")

Description

This method returns all building IDs, one or all translations, the assigned stories and the building metadata.

Parameters

languageCode

An optional lower case ISO 639-1 language and upper case ISO 3166-1 alpha-2 country code seperated by a dash. If specified, only this translation is returned.

Example

"en-US"

Return Values

Returns an Array<Struct> with all buildings on success. When languageCode is specified, each Array element is a Struct with five entries:

Key Type
ID Integer
NAME String
STORIES Array<Integer>
BUILDING_PARTS Array<Integer>
METADATA Struct

The name will be resolved in the following order:

  1. languageCode
  2. en-US
  3. First available language
  4. Empty string

When languageCode is not specified, each Array element is also a Struct with five entries:

Key Type
ID Integer
TRANSLATIONS Struct
STORIES Array<Integer>
BUILDING_PARTS Array<Integer>
METADATA Struct

The key of TRANSLATIONS is the language code and the value the translation.

 

getCategories

Signatures

Array<Struct> getCategories()
Array<Struct> getCategories(String languageCode)

Description

This method returns all category IDs, one or all translations and the category metadata.

Parameters

NameTypeDescriptionExample
languageCodeStringA lower case ISO 639-1 language and upper case ISO 3166-1 alpha-2 country code seperated by a dash.
en-GB

Return Value

Returns an Array<Struct> with all categories on success. When languageCode is specified each Array element is a Struct with three entries: The ID of type Integer, NAME of type String and METADATA of type Struct. If the specified translation is unknown an empty String is returned for NAME. When languageCode is not specified each Array element is also a Struct with three entries: The ID of type Integer, TRANSLATIONS of type Struct with the language code as key and the name as value and METADATA of type Struct.
 

getCategoryMetadata

Signatures

Struct getCategoryMetadata(Integer categoryId)

Description

This method returns the metadata of an existing category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns the categorie's metadata on success.

Errors

CodeDescription
-1Category unknown.
 

getChannelsInCategory

Signatures

Struct getChannelsInCategory(Integer categoryId)

Description

This method returns all channels of a category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns an Struct with all peer IDs as key and all channels as value (Array<Integer>) assigned to the specified category.

Errors

CodeDescription
-1Category unknown.
 

getChannelsInRoom

Signatures

Struct getChannelsInRoom(Integer roomId)

Description

This method returns all channels of a room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns an Struct with all peer IDs as key and all channels as value (Array<Integer>) assigned to the specified room.

Errors

CodeDescription
-1Room unknown.
 

getDevicesInCategory

Signatures

Array<Integer> getDevicesInCategory(Integer categoryId)

Description

This method returns all devices of a category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns an Array<Integer> with all peer IDs assigned to the specified category.

Errors

CodeDescription
-1Category unknown.
 

getDevicesInRoom

Signatures

Array<Integer> getDevicesInRoom(Integer roomId)

Description

This method returns all devices of a room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns an Array<Integer> with all peer IDs assigned to the specified room.

Errors

CodeDescription
-1Room unknown.
 

getRoomMetadata

Signatures

Struct getRoomMetadata(Integer roomId)

Description

This method returns the metadata of an existing room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns the room's metadata on success.

Errors

CodeDescription
-1Room unknown.
 

getRooms

Signatures

Array<Struct> getRooms(String languageCode = "")

Description

This method returns all room IDs, one or all translations and the room metadata.

Parameters

languageCode

An optional lower case ISO 639-1 language and upper case ISO 3166-1 alpha-2 country code seperated by a dash. If specified, only this translation is returned.

Example

"en-US"

Return Values

Returns an Array<Struct> with all rooms on success. When languageCode is specified, each Array element is a Struct with three entries:

Key Type
ID Integer
NAME String
METADATA Struct

The name will be resolved in the following order:

  1. languageCode
  2. en-US
  3. First available language
  4. Empty string

When languageCode is not specified, each Array element is also a Struct with three entries:

Key Type
ID Integer
TRANSLATIONS Struct
METADATA Struct

The key of TRANSLATIONS is the language code and the value the translation.

 

getRoomsInStory

Signatures

Array<Integer> getRoomsInStory(Integer storyId)

Description

This method returns all rooms of a story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
3

Return Value

Returns an Array<Integer> with all room IDs assigned to the specified story.

Errors

CodeDescription
-1Story unknown.
 

getStories

Signatures

Array<Struct> getStories(String languageCode = "")

Description

This method returns all story IDs, one or all translations, the assigned rooms and the story metadata.

Parameters

languageCode

An optional lower case ISO 639-1 language and upper case ISO 3166-1 alpha-2 country code seperated by a dash. If specified, only this translation is returned.

Example

"en-US"

Return Values

Returns an Array<Struct> with all stories on success. When languageCode is specified, each Array element is a Struct with four entries:

Key Type
ID Integer
NAME String
ROOMS Array<Integer>
METADATA Struct

The name will be resolved in the following order:

  1. languageCode
  2. en-US
  3. First available language
  4. Empty string

When languageCode is not specified, each Array element is also a Struct with four entries:

Key Type
ID Integer
TRANSLATIONS Struct
ROOMS Array<Integer>
METADATA Struct

The key of TRANSLATIONS is the language code and the value the translation.

 

getStoriesInBuilding

Signatures

Array<Integer> getStoriesInBuilding(Integer buildingId)

Description

This method returns all stories of a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

Return Values

Returns an Array<Integer> with all story IDs assigned to the specified building.

Exceptions

Code Description
-1 Unknown building.
 

getStoryMetadata

Signatures

Struct getStoryMetadata(Integer storyId)

Description

This method returns the metadata of an existing story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
3

Return Value

Returns the story's metadata on success.

Errors

CodeDescription
-1Story unknown.
 

getSystemVariablesInCategory

Signatures

Array<String> getSystemVariablesInCategory(Integer categoryId)

Description

This method returns all system variables of a category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns an Array<String> with all system variables assigned to the specified category.

Errors

CodeDescription
-1Category unknown.
 

getSystemVariablesInRoom

Signatures

Array<String> getSystemVariablesInRoom(Integer roomId)

Description

This method returns all system variables of a room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns an Array<String> with all system variables assigned to the specified room.

Errors

CodeDescription
-1Room unknown.
 

getVariablesInCategory

Signatures

Struct getVariablesInCategory(Integer categoryId)

Description

This method returns all variables of a category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns variables assigned to the specified category. The root element is a Struct with all peer IDs as key and all channels as value (Struct). The channels again have the variables as value (Array<String>).

Errors

CodeDescription
-1Category unknown.
 

getVariablesInRoom

Signatures

Struct getVariablesInRoom(Integer roomId)

Description

This method returns all variables of a room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns variables assigned to the specified room. The root element is a Struct with all peer IDs as key and all channels as value (Struct). The channels again have the variables as value (Array<String>).

Errors

CodeDescription
-1Room unknown.
 

removeBuildingPartFromBuilding

Signatures

Boolean removeBuildingPartFromBuilding(Integer buildingId, Integer buildingPartId)

Description

This method removes a building part from a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

buildingPartId

The ID of the building part as returned by createBuildingPart() or getBuildingParts().

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building.
-2 Unknown building part.
 

removeCategoryFromChannel

Signatures

Boolean removeCategoryFromChannel(Integer peerId, Integer channel, Integer categoryId)

Description

This method removes a category from a channel.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove the category from.
12
channelIntegerThe channel of the peer to remove the category from. When passing -1 the call is equivalent to removeCategoryFromDevice().
1
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).
 

removeCategoryFromDevice

Signatures

Boolean removeCategoryFromDevice(Integer peerId, Integer categoryId)

Description

This method removes a category from a device.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove the category from.
12
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).
 

removeCategoryFromSystemVariable

Signatures

Void removeCategoryFromSystemVariable(String systemVariableName, Integer categoryId)

Description

This method removes a category from a system variable.

Parameters

NameTypeDescriptionExample
systemVariableNameStringThe name of the system variable to remove the category from.
12
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Unknown room.
-5Unknown variable.
 

removeCategoryFromVariable

Signatures

Boolean removeCategoryFromVariable(Integer peerId, Integer channel, String variableName, Integer categoryId)

Description

This method removes a category from a variable.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove the category from.
12
channelIntegerThe channel of the peer to remove the category from.
1
variableNameStringThe variable of the peer to remove the category from.
TEMPERATURE
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3

Return Value

Returns true on success and false if something went wrong (e. g. unknown channel).
 

removeChannelFromRoom

Signatures

Boolean removeChannelFromRoom(Integer peerId, Integer channel, Integer roomId)

Description

This method removes a channel from a room.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove from the room.
12
channelIntegerThe channel of the peer to remove from the room. When passing -1 the call is equivalent to removeDeviceFromRoom().
1
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns true on success and false on errors (e. g. unknown channel).

Errors

CodeDescription
-1Unknown room.
-2Unknown device.
 

removeDeviceFromRoom

Signatures

Boolean removeDeviceFromRoom(Integer peerId, Integer roomId)

Description

This method removes a device from a room.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove from the room.
12
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns true on success and false on errors (e. g. unknown channel).
 

removeRoomFromStory

Signatures

Boolean removeRoomFromStory(Integer storyId, Integer roomId)

Description

This method removes a room from a story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
3
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Story unknown.
-2Invalid room ID.
 

removeStoryFromBuilding

Signatures

Boolean removeStoryFromBuilding(Integer buildingId, Integer storyId)

Description

This method removes a story from a building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

storyId

The ID of the story as returned by createStory() or getStories().

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building.
-2 Unknown story.
 

removeSystemVariableFromRoom

Signatures

Void removeSystemVariableFromRoom(String systemVariableName, Integer roomId)

Description

This method removes a system variable from a room.

Parameters

NameTypeDescriptionExample
systemVariableNameStringThe name of the system variable to remove from the room.
12
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns Void on success.

Errors

CodeDescription
-1Unknown room.
-5Unknown variable.
 

removeVariableFromRoom

Signatures

Boolean removeVariableFromRoom(Integer peerId, Integer channel, String variableName, Integer roomId)

Description

This method removes a variable from a room.

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to remove from the room.
12
channelIntegerThe channel of the peer to remove from the room.
1
variableNameStringThe variable of the peer to assign to the room.
TEMPERATURE
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3

Return Value

Returns true on success and false on errors (e. g. unknown channel).

Errors

CodeDescription
-1Unknown room.
-2Unknown device.
 

setBuildingMetadata

Signatures

Void setBuildingMetadata(Integer buildingId, Struct metadata)

Description

This method updates the metadata of an existing building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

metadata

Arbitrary metadata.

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building.
 

setBuildingPartMetadata

Signatures

Void setBuildingPartMetadata(Integer buildingPartId, Struct metadata)

Description

This method updates the metadata of an existing building part.

Parameters

buildingPartId

The ID of the building part as returned by createBuildingPart() or getBuildingParts().

metadata

Arbitrary metadata.

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Unknown building part.
 

setCategoryMetadata

Signatures

Void setCategoryMetadata(Integer categoryId, Struct metadata)

Description

This method updates the translations of an existing category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Category unknown.
 

setRoomMetadata

Signatures

Void setRoomMetadata(Integer roomId, Struct metadata)

Description

This method updates the translations of an existing room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Room unknown.
 

setStoryMetadata

Signatures

Void setStoryMetadata(Integer storyId, Struct metadata)

Description

This method updates the metadata of an existing story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
3
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Story unknown.
 

updateBuilding

Signatures

Void updateBuilding(Integer buildingId, Struct translations, Struct metadata = {})

Description

This method updates the translations and metadata of an existing building.

Parameters

buildingId

The ID of the building as returned by createBuilding() or getBuildings().

translations

The name of the building in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the building names in the different languages.

Example

{
    "en-US": "Building 1",
    "de-DE": "Gebäude 1"
}

metadata

Arbitrary metadata.

Return Values

Returns Void on success.

Code Description
-1 Unknown building.
 

updateBuildingPart

Signatures

Void updateBuildingPart(Integer buildingPartId, Struct translations, Struct metadata = {})

Description

This method updates the translations and metadata of an existing building part.

Parameters

buildingPartId

The ID of the building part as returned by createBuildingPart() or getBuildingParts().

translations

The name of the building part in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the building part names in the different languages.

Example

{
    "en-US": "Apartment 1",
    "de-DE": "Wohnung 1"
}

metadata

Arbitrary metadata.

Return Values

Returns Void on success.

Code Description
-1 Unknown building part.
 

updateCategory

Signatures

Void updateCategory(Integer categoryId, Struct translations)
Void updateCategory(Integer categoryId, Struct translations, Struct metadata)

Description

This method updates the translations and metadata of an existing category.

Parameters

NameTypeDescriptionExample
categoryIdIntegerThe ID of the category as returned by createCategory() or getCategories().
3
translationsStructThe name of the category in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the category names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) Light
  }
  [de-DE]
  {
    (String) Licht
  }
}
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Category unknown.
 

updateRoom

Signatures

Void updateRoom(Integer roomId, Struct translations)
Void updateRoom(Integer roomId, Struct translations, Struct metadata)

Description

This method updates the translations and metadata of an existing room.

Parameters

NameTypeDescriptionExample
roomIdIntegerThe ID of the room as returned by createRoom() or getRooms().
3
translationsStructThe name of the room in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the room names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) Living room
  }
  [de-DE]
  {
    (String) Wohnzimmer
  }
}
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Room unknown.
 

updateStory

Signatures

Void updateStory(Integer storyId, Struct translations)
Void updateStory(Integer storyId, Struct translations, Struct metadata)

Description

This method updates the translations and metadata of an existing story.

Parameters

NameTypeDescriptionExample
storyIdIntegerThe ID of the story as returned by createStory() or getStories().
3
translationsStructThe name of the story in different languages. The keys are the lower case ISO 639-1 language codes and the upper case ISO 3166-1 alpha-2 country codes seperated by a dash (e. g. en-US or fr-FR). The values are the story names in the different languages.
(Struct length=2)
{
  [en-US]
  {
    (String) 1st Floor
  }
  [de-DE]
  {
    (String) 1. Obergeschoss
  }
}
metadataStructArbitrary metadata.

Return Value

Returns Void on success.

Errors

CodeDescription
-1Story unknown.
 

System Variables

deleteSystemVariable

Signatures

Void deleteSystemVariable(String name)

Description

This method deletes a system variable created with setSystemVariable.

Parameters

NameTypeDescriptionExample
nameStringThe name of the system variable to be deleted
MySystemVariable

Return Value

Returns Void on success

Errors

CodeDescription
-32602Name is longer than 250 characters.
 

getAllSystemVariables

Signatures

(1) Struct getAllSystemVariables()
(2) Struct getAllSystemVariables(Boolean returnRoomsCategoriesAndFlags)

Description

This method returns all system variables.

Parameters

This method has no parameters.

Return Value

(1) returns a struct with one element for each variable containing the previously stored value. The name of the element is the variable name. (2) returns a struct with the name of the system variable as key and as value the fields VALUE, ROOM, CATEGORIES and FLAGS. The latter three are omitted when undefined.

Example Output

getAllSystemVariables()
(Struct length=3)
{
  [GateLastAction]
  {
    (Integer) 1460479800
  }
  [GateState]
  {
    (Boolean) 0
  }
  [SYSTEM_TEMPERATURE]
  {
    (Float) 44.93
  }
}
 

getSystemVariable

Signatures

Variant getSystemVariable(String name)

Description

This method returns a system variable's value that was previously stored with setSystemVariable().

Parameters

NameTypeDescriptionExample
nameStringThe name as defined in setSystemVariable()
myVariable

Return Value

Returns the value of the system variable

Errors

CodeDescription
-1Variable not found.
-32602Name is longer than 250 characters.

Example Output

getSystemVariable("SYSTEM_TEMPERATURE")
(Float) 45.46

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc '$hg->setSystemVariable("TEST", "Hello Homegear");'
homegear -e rc 'print_v($hg->getSystemVariable("TEST"));'
 

getSystemVariableFlags

Signatures

Integer getSystemVariableFlags(String name)

Description

This method returns the flags previously assigned to a system variable with setSystemVariable().

Parameters

NameTypeDescriptionExample
nameStringThe name as defined in setSystemVariable()
myVariable

Return Value

Returns the flags of the system variable

Errors

CodeDescription
-1Variable not found.
-32602Name is longer than 250 characters.

Example Output

getSystemVariableFlags("SYSTEM_TEMPERATURE")
(Integer) 2

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc '$hg->setSystemVariable("TEST", "Hello Homegear", 2);'
homegear -e rc 'print_v($hg->getSystemVariableFlags("TEST"));'
 

setSystemVariable

Signatures

Void setSystemVariable(String name)
Void setSystemVariable(String name, Variant value)
Void setSystemVariable(String name, Variant value, Integer flags)

Description

This method can be used to store arbitrary data in Homegear's database. You can retrieve this data later by calling getSystemVariable().

Parameters

NameTypeDescriptionExample
nameStringA name of your choice
myVariable
valueVariantThe value to be stored. When ommited the type of the variable is set to Void.
43
flagsIntegerPass 0 for no flags and to not restrict access. The following flags are available:
  • 1: Make variable readonly over all network connections.
  • 2: Make variable invisible and not readable and not writeable over all network connections.
0

Return Value

Returns Void on success

Errors

CodeDescription
-32700Data could not be encoded to binary format.
-32602name is longer than 250 characters.
-32500The limit of 1 million metadata entries has been reached.

Example

/**
 * Execute this command in your terminal
 */
homegear -e rc '$hg->setSystemVariable("TEST", "Hello Homegear");'
homegear -e rc 'print_v($hg->getSystemVariable("TEST"));'
 

UI

addUiElement

Signatures

(1) Integer addUiElement(Integer peerId, Integer channel, String variableName, String label)
(2) Integer addUiElement(String elementId, Struct elementDescription [, Struct metadata = Void])

Description

These methods add an UI element to a Homegear UI module. They work, even if no UI module is installed.

We call method (1) "simple UI element creation". For this signature to work, the variable needs an assigned role. Additionally the variable, channel or peer (checked in this order) needs to assigned to a room. Homegear then tries to match an UI element to the variable. The UI elements to match are defined in Homegear's roles, which are loaded by default from defaultRoles.json. If a UI element needs multiple variables, you can specify any variable in this method. The other variables are matched by role and room automatically.

Signature (2) is much more flexible than signature (1) but also much more complex. It doesn't need any role or room to be assigned to a variable. The UI element itself is matched my it's name (and is defined by default in XML files in /etc/homegear/devices/uiBase). Basically each UI element needs a list of input variables and output variables. So in addition to the UI element name these variables need to be defined. See the parameter descriptions for an example.

Parameters

peerId

The ID of the peer to add an UI element for.

channel

The channel of the peer to add an UI element for.

variable name

The name of the variable to add an UI element for.

label

The label of the UI element which will be displayed in the UI.

elementId

The ID (name) of the UI element as defined in it's XML file.

"Base.lightingSwitch"

elementDescription

A Struct to set label, room and input/output variables for the UI element.

Example

{
    "inputPeers": [
        [
            {
                "peer": 0,
                "channel": -1,
                "name": "LIGHT"
            }
        ]
    ],
    "outputPeers": [
        [
            {
                "peer": 0,
                "channel": -1,
                "name": "LIGHT"
            }
        ]
    ],
    "label": "My light",
    "room": 3
}

metadata

Dynamic metadata which can be overwritten later with setUiElementMetadata() and read with getUiElementMetadata(). It is returned in key dynamicMetadata in the Struct returned by getAllUiElements() The dynamic metadata can also be set in uiElementDescription by specifying it in key dynamicMetadata. Specifying it in metadata takes precedence over dynamicMetadata in elementDescription.

Return Values

Returns the database ID of the newly created UI element.

Exceptions

Code Description
-1 Returned when the input parameters are invalid or the element couldn't be added to the database. For signature (1) additionally when the variable couldn't be matched. The returned error string contains more detauls.

Examples

homegear -e rc '
//Create a new room
$roomId = $hg->createRoom(["en-US" => "Living room", "de-DE" => "Wohnzimmer"]);
//Create a new system variable
$hg->setSystemVariable("TEST", true);
//Assign room to system variable
$hg->addVariableToRoom(0, -1, "TEST", $roomId);
//Assign role "100001" (= Light - state) to system variable
$hg->addRoleToVariable(0, -1, "TEST", 100001);

//Add UI element by using simple UI element creation
$hg->addUiElement(0, -1, "TEST", "My light");
'
 

checkUiElementSimpleCreation

Signatures

Struct checkUiElementSimpleCreation(Integer peerId, Integer channel, String variableName)

Description

This method checks if simple UI element creation is supported by a variable. If it is possible, the variable can be visualized in an UI by calling addUiElement() with peerId, channel, variableName and a label as parameters.

Parameters

peerId

The peer ID to check.

channel

The channel to check.

variableName

The variable name to check.

Return Values

Returns a Struct with the following elements:

Key Optional Type Description
visualizable no Boolean Set to true when the variable can be visualized using simple UI element creation.
reason yes String Only set when visualizable is false. Explains why the variable is not visualizable.
visualized yes Boolean Only set when visualizable is true. Set to true when the variable is already used in a UI element.
uiElements yes Array<Integer> UI elements that visualize this variable.

Exceptions

This method only throws default exceptions.

Examples

homegear -e rc '$hg->setSystemVariable(0, -1, "TEST", true);'
homegear -e rc 'print_v($hg->checkUiElementSimpleCreation(0, -1, "TEST"));'
 

createUiNotification

Signatures

Integer createUiNotification(Struct notificationDescription)

Description

This method creates a new UI notification and stores the provided Struct in Homegear's database. UI notifications are notifications that should be displayed in frontends. When this method is called, Homegear calls the event method uiNotificationCreated. Additionally all notifications can be retrieved by calling getUiNotifications().

It is assumed that there is a page within the frontend for displaying notifications. Without any flags specified, the notification should only be displayed there. When the notification doesn't have buttons, there should be a way to remove the notification, e. g. by displaying a "remove" button which triggers a call to removeUiNotification.

When selecting an element within the notification list, an optional modal can be shown. The modal can have an arbitrary number of buttons. Pressing a button must call uiNotificationAction. This triggers the associated action within Homegear. The action is user defined, i. e. in Node-BLUE or an IPC client. Pressing a button mustn't call removeUiNotification. Removing the notification should be handled within the user's custom logic in Homegear.

In addition to this default behaviour there are two more options:

  1. The notification can be displayed as an overlay with or without buttons.
    • When there is a modal defined, selection the overlay should open the modal. No buttons should be displayed within the overlay itself in this case.
    • When there is no modal defined, buttons should be displayed within the overlay.
    • When there are no buttons defined, the overlay should be closeable another way (i. e. by displaying a "X" button).
  2. The notification can be displayed as a modal that is shown regardless which frontend page is open. The user needs to interact with the modal in order to be able to use the frontend. This can be used for example to show terms and conditions.

Parameters

notificationDescription

The following fields are predefined by Homegear and should be used:

Key Mandatory Type Description
type yes String An arbitrary type string to identify notifications of the same category.
flags no Struct Modifiers defining how the notification should be displayed.
flags/overlayNotification no Boolean Notification should be displayed as an overlay.
flags/closeable no Boolean Only applicable when overlayNotification is true. Forces the overlay notification to be closable.
flags/hasModal no Boolean When set, the notification has a modal.
flags/overlayModal no Boolean Only applicable when hasModal is true. Forces the modal to be shown within the frontend. The user can't use the frontend without interacting with the modal first.
title yes Struct A short text describing the notification. This title is shown in the notification list and within the overlay. The title must be provided for every supported language. Fallback language is en-US.
modalTitle no Struct Only applicable when hasModal is true. This title is shown at the top of the modal. The title must be provided for every supported language. Fallback language is en-US.
modalContent no Struct Only applicable when hasModal is true. This defines the modal content as HTML. The content must be provided for every supported language. Fallback language is en-US.
buttons no Array<Struct> Defines buttons to interact with the notification. I. e. "yes" - "no" or "accept" - "decline".
buttons/#/id no Integer The ID of the button starting with 0.
buttons/#/type no String This just defines a CSS class to use. E. g. "success", "warning", "error".
buttons/#/reloadUi no Boolean The UI should be reloaded after selecting this button.
buttons/#/closeModal no Boolean Pressing this button should close the modal.
buttons/#/label no Struct The label of the button. It must be provided for every supported language. Fallback language is en-US.
buttons/#/icon no String The icon or icon class to use.

In addition to these fields, more data can be inserted into the Struct. Homegear returns the additional data as provided.

Example

An example description might look like this:

{
  "type": "my-notification-type",
  "flags": {
    "closeable": true,
    "hasModal": true,
    "overlayNotification": true,
    "overlayModal": false
  },
  "title": {
    "en-US": "Please do something",
    .
    .
    .
  },
  "modalTitle": {
    "en-US": "My Modal",
    .
    .
    .
  },
  "modalContent": {
    "en-US": "<p>My HTML</p>"
  },
  "buttons": [
    {
      "id": 0,
      "type": "success",
      "reloadUi": true,
      "closeModal": true,
      "label": {
        "en-US": "OK"
      },
      "icon": "my-icon",
      "my-data": [0, 1, 2, 3]
    },
    .
    .
    .
  ],
  "my-data": {"first": 0, "second": 1}
}

Return Values

Returns the ID of the new notification on success.

Exceptions

This method only throws default exceptions.

 

getAllUiElements

Signatures

Array<Struct> getAllUiElements(String language)

Description

This method returns all UI elements previously created with addUiElement().

Parameters

language

The language to return the UI elements for. E. g. en-US or de-DE.

Return Values

Returns an Array with all UI elements. Note that the database ID is encoded in the key databaseId.

Exceptions

This method only throws default exceptions.

 

getAvailableUiElements

Signatures

Array<Struct> getAvailableUiElements(String language)

Description

This method returns all UI elements that can be added with addUiElement().

Parameters

language

The language to return the UI elements for. E. g. en-US or de-DE.

Return Values

Returns an Array with the available UI elements.

Exceptions

This method only throws default exceptions.

 

getCategoryUiElements

Signatures

Array<Struct> getCategoryUiElements(Integer category, String language)

Description

This method returns all UI elements assigned to the specified category. The assigned categories can be specifed in addUiElement() by placing an Array with category IDs in the key categories.

Parameters

category

The ID of the category to return UI elements for.

language

The language to return the UI elements for. E. g. en-US or de-DE.

Return Values

Returns an Array with all UI elements within the specified category.

Exceptions

Code Description
-1 The category is unknown.
 

getRoomUiElements

Signatures

Array<Struct> getRoomUiElements(Integer room, String language)

Description

This method returns all UI elements assigned to the specified room. The assigned room can be specifed in addUiElement() by placing the room ID in the key room.

Parameters

room

The ID of the room to return UI elements for.

language

The language to return the UI elements for. E. g. en-US or de-DE.

Return Values

Returns an Array with all UI elements within the specified room.

Exceptions

Code Description
-1 The room is unknown.
 

getUiElementMetadata

Signatures

Struct getUiElementMetadata(Integer databaseId)

Description

Returns metadata previously stored with addUiElement() or setUiElementMetadata().

Parameters

databaseId

The ID of the UI element as returned by the get methods in the key databaseId.

Return Values

Returns the metadata Struct.

Exceptions

Code Description
-1 Returned when the UI element is not found.
 

getUiNotification

Signatures

Struct getUiNotification(Integer notificationId, String languageCode)

Description

This method returns a single UI notification previously created with createUiNotification.

Parameters

notificationId

The ID of the notification.

languageCode

The language code to return, e. g. de-DE. The fallback language code is en-US.

Return Values

Returns an the notification description on success.

Exceptions

Code Description
-1 Returned when the UI notification is not found.
 

getUiNotifications

Signatures

Array<Struct> getUiNotifications(String languageCode)

Description

This method returns all UI notifications previously created with createUiNotification.

Parameters

languageCode

The language code to return, e. g. de-DE. The fallback language code is en-US.

Return Values

Returns an array with all notification descriptions on success.

Exceptions

This method only throws default exceptions.

 

removeUiElement

Signatures

Void removeUiElement(Integer databaseId)

Description

Deletes an UI element previously created with addUiElement().

Parameters

databaseId

The ID of the UI element as returned by the get methods in the key databaseId.

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Returned when the database ID is invalid.
-2 Returned when the UI element is not found.
 

removeUiNotification

Signatures

Void removeUiNotification(Integer notificationId)

Description

This method removes a UI notification previously created with createUiNotification. When this method is called, Homegear calls the event method uiNotificationRemoved.

Parameters

notificationId

The ID of the notification to remove.

Return Values

Returns Void on success.

Exceptions

This method only throws default exceptions.

 

requestUiRefresh

Signatures

Void requestUiRefresh(String id)

Description

This method should cause a Homegear UI to reload and triggers the event method requestUiRefresh().

Parameters

id

An arbitrary ID which is passed to requestUiRefresh(). It can be used to identify a specific UI. When empty, all UIs should be refreshed.

Return Values

Returns Void on success.

 

setUiElementMetadata

Signatures

Void setUiElementMetadata(Integer databaseId, Struct metadata)

Description

Updates the metadata stored for an UI element previously created with addUiElement(). It can be read again with getAllUiElements() (placed in the key dynamicMetadata) or with getUiElementMetadata().

Parameters

databaseId

The ID of the UI element as returned by the get methods in the key databaseId.

metadata

The metadata to set.

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Returned when the UI element is not found.
 

uiNotificationAction

Signatures

Void uiNotificationAction(Integer notificationId, Integer buttonId)

Description

This method should be called by the UI when a UI notification button is pressed by the user. When this method is called, Homegear calls the event method uiNotificationAction. This event method can be catched in Homegear's script engine, an IPC client or Node-BLUE to trigger an action and remove the notification when done.

Parameters

notificationId

The ID of the notification.

buttonId

The ID of the button that was pressed..

Return Values

Returns Void on success.

Exceptions

Code Description
-1 Returned when the UI notification is not found.
 

Variable Profiles

activateVariableProfile

Signatures

Boolean activateVariableProfile(Integer profileId)

Description

This method activates a variable profile previously created using addVariableProfile().

Parameters

profileId

The ID of the profile as returned by addVariableProfile() or the key id of the get methods.

Return Values

Returns true on success and false on errors.

Exceptions

Code Description
-1 The profile ID is unknown.

Examples

homegear -e rc '
$hg->setSystemVariable("TEST1", false);
$hg->setSystemVariable("TEST2", 93);
$hg->setSystemVariable("TEST3", "Hello World");

$profileId = $hg->addVariableProfile([
    "en-US" => "My profile",
    "de-DE" => "Mein Profil"
], [
    "values" => [
        [0, -1, "TEST1", true],
        [0, -1, "TEST2", 47],
        [0, -1, "TEST3", "Hello Homegear"]
    ]
]);

$hg->activateVariableProfile($profileId);
print_v($hg->getSystemVariable("TEST1"));
print_v($hg->getSystemVariable("TEST2"));
print_v($hg->getSystemVariable("TEST3"));
'
 

addVariableProfile

Signatures

Integer addVariableProfile(Struct translations, Struct profile)

Description

This method adds a variable profile to Homegear. A variable profile is a set of predefined variable states. It can be activated by calling activateVariableProfile(). A profile can be assigned to a room.

Parameters

translations

A Struct with language/name pairs of the profile:

{
    "en-US": "My profile",
    "de-DE": "Mein Profil"
}

profile

The profile itself. The content of the profile Struct can be chosen freely. Either the key values or the key roles is mandatory. It is allowed to specify both.

Mandatory elements of the values array

values is an Array. Each element again is a Struct with the following mandatory elements:

Key Type Description
peerId Integer The peer ID of the variable to set.
channel Integer The channel of the variable to set.
variable String The name of the variable to set.
value Variant The value to set.

Mandatory elements of the roles array

roles is an Array. Each element again is an Array with the following mandatory elements:

Key Type Description
role Integer All variables with this role will be set to value.
value Variant The value to set.

Optional elements of a values and roles array entry

In addition there are the following optional elements available in both a values entry and a roles entry:

Key Type Default Description
wait Boolean false Wait for a value to be sent to the device before setting the next value.
ignoreValueFromDevice Boolean true Ignore values from device for detection if a profile is currently active.
deviceRefractoryPeriod Integer 60 Only used when ignoreValueFromDevice is false. For this number of seconds values from the device are ignored for detection if a profile is currently active.

Please note that adding or removing variables to/from the specified roles after the profile has been created requires a Homegear restart or a call to updateVariableProfile() for the profile to work.

Optional elements of the profile struct

Key Type Default Description
room Integer When specified the profile is associated to this room.

Example

{
    "myOptionalKey": ["myOptionalArray"],
    "room": 12,
    "values": [
        {
            "peerId": 12,
            "channel": 1,
            "variable": "STATE",
            "value": true
        },
        {
            "peerId": 14,
            "channel": 2,
            "variable": "LEVEL",
            "value": 47
        }
    ]
}

Return Values

Returns the ID of the newly created profile.

Exceptions

Code Description
-1 The parameters are invalid or the profile could not be inserted into the database.

Examples

With variables

homegear -e rc '
$hg->setSystemVariable("TEST1", false);
$hg->setSystemVariable("TEST2", 93);
$hg->setSystemVariable("TEST3", "Hello World");

$profileId = $hg->addVariableProfile([
    "en-US" => "My profile",
    "de-DE" => "Mein Profil"
], [
    "values" => [
        [
            "peerId" => 0,
            "channel" => -1,
            "variable" => "TEST1",
            "value" => true
        ],
        [
            "peerId" => 0,
            "channel" => -1,
            "variable" => "TEST2",
            "value" => 47
        ],
        [
            "peerId" => 0,
            "channel" => -1,
            "variable" => "TEST3",
            "value" => "Hello Homegear"
        ]
    ]
]);

$hg->activateVariableProfile($profileId);
print_v($hg->getSystemVariable("TEST1"));
print_v($hg->getSystemVariable("TEST2"));
print_v($hg->getSystemVariable("TEST3"));
'

With roles

homegear -e rc '
$hg->setSystemVariable("TEST1", false);
$hg->setSystemVariable("TEST2", true);
$hg->setSystemVariable("TEST3", true);

$hg->addRoleToVariable(0, -1, "TEST1", 100001);
$hg->addRoleToVariable(0, -1, "TEST2", 100001);
$hg->addRoleToVariable(0, -1, "TEST3", 100001, 2, true); //Invert

$profileId = $hg->addVariableProfile([
    "en-US" => "My profile",
    "de-DE" => "Mein Profil"
], [
    "roles" => [
        [
            "role" => 100001,
            "value" => true
        ]
    ]
]);

$hg->activateVariableProfile($profileId);
print_v($hg->getSystemVariable("TEST1"));
print_v($hg->getSystemVariable("TEST2"));
print_v($hg->getSystemVariable("TEST3"));
'
 

deleteVariableProfile

Signatures

Void deleteVariableProfile(Integer profileId)

Description

This method deletes a variable profile previously created using addVariableProfile().

Parameters

profileId

The ID of the profile as returned by addVariableProfile() or the key id of the get methods.

Return Values

Returns Void on success.

Exceptions

This method only throws default exceptions.

 

getAllVariableProfiles

Signatures

Array<Struct> getAllVariableProfiles()
Array<Struct> getAllVariableProfiles(String language)

Description

This method returns all variable profiles previously created with addVariableProfile().

Parameters

language

The language to fill the key name of the returned Struct with. E. g. en-US or de-DE.

Return Values

Returns an Array with all variable profiles. The following keys are inserted by Homegear in addition to the content specified in addVariableProfile():

Key Type Description
id Integer The ID of the profile.
name String The language-specific profile name. Only returned, when language code is specified.
translations Struct The profile name in all specified languages. Only returned, when language code is not specified.
isActive Boolean true when the profile is currently active.
totalVariableCount Integer The total number of variables in this profile.
activeVariableCount Integer The number of variables specified in this profile that match the profile value.

Exceptions

This method only throws default exceptions.

 

getVariableProfile

Signatures

Struct getVariableProfile(Integer profileId)
Struct getVariableProfile(Integer profileId, String language)

Description

This method returns a single variable profile previously created with addVariableProfile().

Parameters

profileId

The ID of the profile as returned by addVariableProfile() or getAllVariableProfiles().

language

The language to fill the key name of the returned Struct with. E. g. en-US or de-DE. When not specified all translations are returned.

Return Values

Returns the specified variable profile Struct. The following keys are inserted by Homegear in addition to the content specified in addVariableProfile():

Key Type Description
id Integer The ID of the profile.
name String The language-specific profile name. Only returned, when language code is specified.
translations Struct The profile name in all specified languages. Only returned, when language code is not specified.
isActive Boolean true when the profile is currently active.
totalVariableCount Integer The total number of variables in this profile.
activeVariableCount Integer The number of variables specified in this profile that match the profile value.

Exceptions

Code Description
-1 The profile ID is unknown.
 

updateVariableProfile

Signatures

Struct updateVariableProfile(Integer profileId, Struct translations, Struct profile)

Description

This method updates a variable profile previously created with addVariableProfile(). If an empty Struct is passed to translations or profile, this parameter is not updated. Like this it is possible to only update the profile or the translations. After adding variables to a role or removing variables from a role, all profiles with this role need to be updated. This can be done by restarting Homegear or by calling this method with translations and profile being an empty Struct.

Parameters

profileId

The ID of the profile as returned by addVariableProfile() or the key id of the get methods.

translations

See addVariableProfile().

profile

See addVariableProfile().

Return Values

Returns true on success and false on errors.

Exceptions

Code Description
-1 The profile ID is unknown.
 

Event Server - Devices

event

Signatures

Void event(String eventSource, Integer peerId, Integer channel, String variable, Variant value)

Description

This method is called when a parameter of the parameter set VALUES, a system variable or metadata of a device is changed.

Parameters

NameTypeDescriptionExample
eventSourceStringWhen the events are not sent over the same connection as incoming RPC calls, eventSource is set to the interface ID as specified in init(). Otherwise it is set to the instance causing the variable update. Possible values are: device-[Peer ID], scriptEngine, ipcServer, profileManager, homegear, rpc-client-[address]:[port] or the interface ID as specified in init() of the network client updating the variable.
0
peerIdIntegerThe ID of the device whose parameter or metadata was changed. 0 for system variables.
32
channelIntegerThe index of the channel whose parameter was changed. -1 for system variables and metadata.
2
variableStringThe name of the parameter as defined in the XML file or the name of the system or metadata variable.
STATE
valueVariantThe new value. The type of the value is defined in the XML file, by setSystemVariable() or setMetadata(). When a system variable is deleted, value is a Struct with two elements: TYPE with the integer value 0 and CODE with integer value 1. When a metadata variable is deleted, value is also a Struct with the same two keys, but TYPE has a value of 1.
1

Return Value

Returns Void on success.
 

Event Server - General

error

Signatures

Void error(String interfaceId, Integer level, String message)

Description

This method is called when an error occurs within Homegear. It is raised for messages of log level 1 (critical), 2 (error) and 3 (warning).

Parameters

NameTypeDescriptionExample
interfaceIdStringThe interface ID as specified in init().
0
levelIntegerThe log level of the error message. Possible values are 1 (critical), 2 (error) or 3 (warning).
2
messageStringThe error message.
Module HomeMatic BidCoS: HM-LGW "Living Room": Warning: Connection closed. Trying to reconnect...

Return Value

Returns Void on success.
 

Event Server - UI

requestUiRefresh

Signatures

Void requestUiRefresh(String id)

Description

This method should cause a Homegear UI to reload and is triggered by calling requestUiRefresh().

Parameters

id

An arbitrary ID passed to requestUiRefresh(). It can be used to identify a specific UI.

Return Values

Returns Void on success.

 

uiNotificationAction

Signatures

Void uiNotificationAction(Integer notificationId, String type, Integer buttonId)

Description

This method is called by Homegear when uiNotificationAction is called and indicates a button press by the user.

Parameters

notificationId

The ID of the notification.

type

The type of the notification as provided to createUiNotification.

buttonId

The ID of the button that was pressed.

Return Values

Returns Void on success.

 

uiNotificationCreated

Signatures

Void uiNotificationCreated(Integer notificationId)

Description

This method is called by Homegear when createUiNotification is called and the element has successfully been stored to database. To retrieve additional information, call getUiNotification.

Parameters

notificationId

The ID of the new notification.

Return Values

Returns Void on success.

 

uiNotificationRemoved

Signatures

Void uiNotificationRemoved(Integer notificationId)

Description

This method is called by Homegear when removeUiNotification is called and the element has been removed from the database.

Parameters

notificationId

The ID of the removed notification.

Return Values

Returns Void on success.

 

Event Server - Variable Profiles

variableProfileStateChanged

Signatures

Void variableProfileStateChanged(Integer profileId, Boolean state)

Description

This method is called when a variable profile changes it's state to active or inactive. Active means that the variable values specified in the profile match the current values of the variables.

Parameters

profileId

The ID of the profile.

state

The current state of the profile. true for active and false for inactive.

Return Values

Returns Void on success.