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.
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
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
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 CategoriesaddSystemVariableToRoomAssigns a system variable to a room
Rooms and CategoriesaddVariableToRoomAssigns a variable to a room
Rooms and CategoriescreateCategoryCreates a new category
Rooms and CategoriescreateRoomCreates a new room
Rooms and CategoriescreateStoryCreates a new story
Rooms and CategoriesdeleteCategoryDeletes a category
Rooms and CategoriesdeleteRoomDeletes a room
Rooms and CategoriesdeleteStoryDeletes a story
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 all information about all rooms
Rooms and CategoriesgetRoomsInStoryReturns all rooms of a story
Rooms and CategoriesgetStoriesReturns information about all stories
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 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 CategoriesremoveSystemVariableFromRoomRemoves a system variable from a room
Rooms and CategoriesremoveVariableFromRoomRemoves a variable from a room
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 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 VariablessetSystemVariableCreates or updates a system variable

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 - Device EventseventCalled on variable changes
Event Server - GeneralerrorCalled when an error occurs in Homegear
 

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.
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

getServiceMessages

Signatures

Array<Array<Variant>> getServiceMessages(bool returnID)

Description

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

Parameters

NameTypeDescriptionExample
returnIDBooleanRecommended. If true, Homegear returns the peer ID instead of the "address" (serial number and channel separated by a colon). By default, the address is returned for compatibility reasons.
True

Return Value

This returns an array, and each element in the array is a service message.
If returnID is true, the element is, in turn, an array with four elements:

  1. Integer: The ID of the peer
  2. Integer: The channel for which the service message is set
  3. String: The ID of the service message (LOWBAT, UNREACH, ...)
  4. Boolean or integer: The value of the service message

If returnID is false or not set, the element is an array with three elements:

  1. String: The address of the device (serial number and channel separated by a colon)
  2. String: The ID of the service message (LOWBAT, UNREACH, ...)
  3. Boolean or integer: The value of the service message
Types of Service Messages

There are four service messages available for all devices:

  1. UNREACH (Boolean): A device is currently unreachable.
  2. STICKY_UNREACH (Boolean): A device was unreachable at some point.
  3. CONFIG_PENDING (Boolean): There are configuration parameters that need to be sent to the device.
  4. LOWBAT (Boolean): Low battery.

Example Output

getServiceMessages(true)
(Array length=3)
{
  (Array length=3)
  {
    (Integer) 43
    (Integer) 0
    (String) LOWBAT
    (Boolean) 1
  }
  (Array length=3)
  {
    (Integer) 16
    (Integer) 0
    (String) UNREACH
    (Boolean) 1
  }
  (Array length=3)
  {
    (Integer) 67
    (Integer) 0
    (String) ERROR
    (Integer) 7
  }
}
 

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)

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
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)
Void setValue(Integer peerId, Integer channel, String variableName, Variant value, Boolean wait)

Description

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

Deprecated - For compatability only
Void setValue(String address, String variableName, Variant value)
Void setValue(String address, String variableName, Variant value, Boolean, wait)

Parameters

NameTypeDescriptionExample
peerIdIntegerThe ID of the peer to set the value for or 0 to set or create a system variable.
131
channelIntegerThe channel of the peer to set the value for or -1 to set or create a metadata or system variable.
3
variableNameStringThe name of the variable to set.
SETPOINT_TEMPERATURE
valueVariantThe 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). 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:
  • +=
  • -=
  • *=
  • /=
  • !
! toggles a Boolean value and 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: +=0.5
21.0
waitBooleanSet 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.
true
addressStringThe serial number and channel of the device to set the value for (separated by a colon)
JEQ0123456:1
or
JEQ0123456

Return Value

Returns Void on success

Errors

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

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"));'
 

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 url, String interfaceId)
Void init(String url, String interfaceId, Integer flags)

Description

This method is used to register or unregister an RPC event server with Homegear. After calling this method, Homegear's RPC client starts sending events and device updates to the registered server (see the section on RPC client methods). It is not necessary to call init() for MQTT or WebSockets.

Parameters

NameTypeDescriptionExample
urlStringThe URL of the event server that you want to register, including 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
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

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)

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

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.
 

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

Integer createDevice(Integer familyId, Integer deviceType, String serialNumber, Integer address, Integer firmwareVersion)
Integer createDevice(Integer familyId, Integer deviceType, String serialNumber, Integer address, Integer firmwareVersion, String interfaceId)

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

Return Value

Returns the ID of the new device on success

Errors

CodeDescription
-2The device family is unknown or unavailable.
-5A device with this serial number or address already exists.
-6This device type is unknown.
-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)

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

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.
 

Rooms and Categories

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
storyIntegerThe 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.
 

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.
 

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.
 

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.
 

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()
Array<Struct> getRooms(String languageCode)

Description

This method returns all room IDs, one or all translations and the room 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 rooms 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.
 

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()
Array<Struct> getStories(String languageCode)

Description

This method returns all story IDs, one or all translations, the assigned rooms and the story 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 stories on success. When languageCode is specified each Array element is a Struct with four entries: The ID of type Integer, NAME of type String, ROOMS of type Array<Integer> 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 four entries: The ID of type Integer, TRANSLATIONS of type Struct with the language code as key and the name as value, ROOMS of type Array<Integer> and METADATA of type Struct.
 

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.
 

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, 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.
 

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.
 

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 translations 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.
 

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 returnRoomsAndCategories)

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 and CATEGORIES. The latter two 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"));'
 

setSystemVariable

Signatures

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

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

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"));'
 

Event Server - Device Events

event

Signatures

Void event(String interfaceId, 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
interfaceIdStringThe interface ID as specified in init().
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.