LaRoomy Transmission Protocol

This section describes the transmission protocol which is working in the background.

Table of Content

Transmission Protocol Header

All transmission strings have a fixed header length of 8 byte and all transmissions must be delimited with a carriage return. The payload data must be appended (if there is data) and the data size entry of the transmission header must be set to the exact size. For the transmission-type and the error or status values see the tables below.

Byte-Index Description Type
0 Transmission Type Single char
1 Transmission Sub Type Single char
2 Element Index Dual hex Char
3 Element Index Dual hex Char
4 Transmission PayLoad Data Size Dual hex Char
5 Transmission PayLoad Data Size Dual hex Char
6 Error Flag Single char
7 Status Flag Single char
Transmission Type (0)

The Transmission Type defines the main object of the transmission. It is the first instance for the transmission dispatcher. The purpose exist in duplicate, one for normal transmission and one for fragmented transmission.

Char Description
0 Invalid Character
1 Property Data Transmission
2 Group Data Transmission
3 Property State Transmission
4 Property Execution Transmission
5 Notification/Command Transmission
6 Binding Transmission
7 Init Transmission
8 Fast Data Pipe Transmission
9 Fast Data Pipe (Fragmented Transmission)
a Property Data (Fragmented Transmission)
b Group Data (Fragmented Transmission)
c Property State (Fragmented Transmission)
d Property Execution (Fragmented Transmission)
e Notification/Command (Fragmented Transmission)
f Binding (Fragmented Transmission)
Sub Type (1)

The Transmission Sub Type defines the purpose and the direction of the transmission.

Char Description
0 Invalid
1 Request
2 Response
3 Command
4 Update
5 Insert
6 Remove
7 Enable
8 Disable
Element Index (2:3)

In a Property or Group transmission the Element-Index defines the position of the element inside the element-stack. In other transmissions the values must be set to zero. The format is an 8bit hexadecimal value as string (2 char).

Data Size (4:5)

The Data Size must be set to the payload data size. The format is an 8bit hexadecimal value as string (2 char).

If the data-size of the full transmission (payload-data + header-size) exceeds the 8bit frame, the data-size must be set to the maximum ('ff') and the Oversize value must be set in the status flag field.
If the transmission is fragmented, the LAST fragment must also have the Oversize Stop flag value set in the status flag field.

Error Flag (6)

As the name says the Error-Flag is a marker in a response to an invalid transmission.

Char Description
0 No Error
1 Unknown Error
2 Transmission undeliverable
3 Index out of bounds
Status Flag (7)

The Status-Flag is used to indicate the result of an operation.

Char Description
0 Success
1 Fail
2 Reserved
3 Start
4 End
5 Oversize
6 Reserved
7 Oversize Stop
Init Transmission

The first transmission which is sent from App to Device after the connection is established is an init request. The init request contains no payload data.

The remote device must respond with an init response. The response data must be aligned as follows:

Byte-Index Description Type
8 Property Count Dual hex char
9 Property Count Dual hex char
10 Group Count Dual hex char
11 Group Count Dual hex char
12 Data caching permission Single Char
13 Binding Passkey Required Single Char
14 Standalone Property Mode Single Char
15 Reserved - must be zero Char
16 Reserved - must be zero Char
17 Reserved - must be zero Char
18 Delimiter <CR> Char
Property Count (8:9)

The total amount of properties. When properties are retrieved during a property loop this parameter determins how many properties are requested. The format is an 8bit hexadecimal value as string (2 char).

Group Count (10:11)

The total amount of groups. When groups are retrieved during a group loop this parameter determins how many groups are requested. The format is an 8bit hexadecimal value as string (2 char).

Data caching permission (12)

This character defines if the app can cache the properties and groups and load it from cache the next time a connection is established. 1 = caching is permitted / 0 = not allowed.

Binding Passkey Required

If this character is set to 1 device binding is required, this means that the app will send an authentication request before properties are retrieved.

Standalone Property Mode

When set to 1, the standalone mode is requested for this device. Note that Standalone Mode only works if the property count is 1 and the property type is complex.

Reserved character (15:16:17)

These character are reserved and must be set to 0.

Property Request Transmission

A Property Request Transmission is sent from App to Device. It contains a language identification to determine the language of the app user to enable the possibility to respond with language dependent property descriptors.

Byte-Index Description Type
8 Language ID Char
9 Language ID Char
10 Delimiter <CR> Char
Language ID (8:9)

The Language ID is a 2-letter code in ISO 639-1 format. More Info.

Property Response Transmission

The remote device must respond to a property request with a property response. A Property Response Transmission contains all necessary data for the appearance and the construction of a property element.

Byte-Index Description Type
8 Property Type Dual hex char
9 Property Type Dual hex char
10 Image ID Dual hex char
11 Image ID Dual hex char
12 Group Index Dual hex char
13 Group Index Dual hex char
14 Flags Dual hex char
15 Flags Dual hex char
16 Property State Dual hex char
17 Property State Dual hex char
18 .. Property Descriptor String
.. End Delimiter <CR> Char
Property Type (8:9)

The Property-Type determins the appearance and the functionality of the property element. The format is an 8bit hexadecimal value as string (2 char).

Value Property Type
1 Button
2 Switch
3 Level Selector
4 Level Indicator
5 Text Display
6 Option Selector
7 RGB Selector
8 Extended Level Selector
9 Time Selector
10 Time Frame Selector
11 Date Selector
12 Unlock Control
13 Navigator Control
14 Bar Graph
15 Line Graph
16 String Interrogator
17 Text List Presenter
Image ID (10:11)

The Image-ID defines the image to display in the property element. The Image-Table is accessible here. The format is an 8bit hexadecimal value as string (2 char).

Group Index (12:13)

If the property element is part of a property group, this parameter defines the index of the group to which the element belongs. Note that the group-member-flag in the flag parameter must be also set, otherwise this parameter is ignored. The format is an 8bit hexadecimal value as string (2 char).

Flags (14:15)

Additional flags for the element can be set in this parameter. The following flags are available:

Flag Value Description
0x01 Property is Group-Member
0x02 Property is disabled

The format is an 8bit hexadecimal value as string (2 char).

Property State (16:17)

When the property element is a property type with simple state data, this parameter is the simple property state. Otherwise this parameter is not used. The format is an 8bit hexadecimal value as string (2 char).

Property Descriptor (18..End)

The property descriptor is the text which is displayed in the property element. For some properties the descriptor has special syntax to carry more than one text element. The format is an ASCII based string. All unicode characters must be escaped.

Group Request Transmission

A Group Request Transmission is sent from App to Device. It contains a language identification to determine the language of the app user to enable the possibility to respond with language dependent group descriptors.

Byte-Index Description Type
8 Language ID Char
9 Language ID Char
10 Delimiter <CR> Char
Language ID (8:9)

The Language ID is a 2-letter code in ISO 639-1 format. More Info.

Group Response Transmission

The remote device must respond to a Group-Request with a Group-Response. A Group-Response transmission contains all necessary data for the appearance and the construction of a propterty group.

Byte-Index Description Type
8 Member Count Dual hex char
9 Member Count Dual hex char
10 Image ID Dual hex char
11 Image ID Dual hex char
12 .. Descriptor String
.. End Delimiter <CR> Char
Member-Count (8:9)

The amount of member in this group. The format is an 8bit hexadecimal value as string (2 char).

Image ID (10:11)

The Image-ID defines the image to display in the group header. The Image-Table is accessible here. The format is an 8bit hexadecimal value as string (2 char).

Group Descriptor (12..End)

The group descriptor is the text which is displayed in the group header. The format is an ASCII based string. All unicode characters must be escaped.

Property State Data Transmission

The Property-State transmission must be sent from the remote device in response to a Property-State-Request or is sent to update the state if it has changed on device-side. The State transmission contains all necessary data for the definition of the state of a specific property. Please note, that a state transmission must have the appropriate property-index set in byte-fields (2:3) to assign the state to the property.

For Properties with complex state data, the state data is type specific. Click here to see the details.

For a property element with simple state data, the payload is defined in the following manner:

Byte-Index Description Type
8 Property State Dual hex char
9 Property State Dual hex char
10 Delimiter <CR> Char
Property State (8:9)

The 8bit property state value of a simple property. The format is an 8bit hexadecimal value as string (2 char). The purpose of the simple state value depends on the type of the simple property:

Property-Type State Purpose
Button The state value is ignored, because the button property has no state.
Switch The state value defines if the switch is on or off. If it is on, the value is 1, otherwise 0.
Level-Selector The state carries the level of the selector. The state value has a range from 0 (zero level) to 255 (full level).
Level-Indicatior The state carries the level to indicate. The state value has a range from 0 (zero level) to 255 (full level).
Text-Display The state value is ignored, because the text-display property has no state.
Option-Selector The state value carries the current selected option index.
Property Execution Transmission

If a property is executed, the app-user has interacted with it and it's state has changed. In fact, the property execution transmission is a property state transmission from app to remote device. Therefore the payload data is the same as in a property state data transmission, except that values which affects the visibility of elements in the user-interface of the app are not set. For specific info of the layout of the complex property state transmission see the appropriate page. For properties with simple state the the payload is defined in the following manner:

Byte-Index Description Type
8 Property State Dual hex char
9 Property State Dual hex char
10 Delimiter <CR> Char
Property State (8:9)

The 8bit property state value of a simple property. The format is an 8bit hexadecimal value as string (2 char).

Binding Transmission

Binding tansmissions have three purposes: Enable, Release or Authenticate.

Byte-Index Description Type
8 Binding Action Type Single char
9 Status Value Single char
10 .. Binding PassKey String
.. End Delimiter <CR> Char
Binding Action Type (8)

The binding action type defines the purpose of the binding transmission:

Value Description
0 Release
1 Enable
2 Authenticate
3 Unused
Status Value (9)

The status value is used in a response from device to app to indicate the result of an operation:

Value Description
0 Success
1 Authentication failed
2 Binding not supported
3 Release failed
4 Unknown error
Binding PassKey (10..End)

If this is an enable or authentication transmission, the passkey is appended. Otherwise the delimiter is on position 10. The key has a maximum length of 10 character. Only ASCII characters are transmitted.

Device to App Command Transmission

As the name says, this transmission is sent from device to app, to execute an action or request some data. If the command-type does not require extra specific data, the delimiter is expected on position 9.

Byte-Index Description Type
8 Command Type Single char
9 .. Specific Command Data Command-Dependent
.. End Delimiter <CR> Char
Command Type (8)

The command type determins the purpose of the command transmission.

Value Description Payload Data
0 Reserved - Do not use None
1 User Message Command See Table below
2 Time Request None
3 Invalidate Properties Command (force Property-Reload) None
4 Save Properties to Cache Command None
5 Language Request None
6 Refresh all property states Command None
7 Navigate-Back Command None
8 Close Device Command None
9 Date Request None
a UI-Mode Info Request None
User Message Command

The User-Message-Command is used to send a notification to the app-user. It will be displayed in a notification area. The message transmission has 3 severity types: info, warning and error. Additional a display time could be defined. The payload data alignment is defined as follows:

Byte Index Description Type
8 Severity Type Single Char
9 Display Time Single Char
10 .. Message start String
.. End Delimiter <CR> Char
Severity Type (8)

The Severity Type affects the color of the displayed message.

Value Description
0 Info
1 Warning
2 Error
Display Time (9)

The Display-Time is the holding time for the message. If the time is elapsed, the message will be hidden.

Value Description
0 5 seconds
1 7.5 seconds
2 10 seconds
3 12.5 seconds
4 15 seconds
5 17.5 seconds
6 20 seconds
9 Infinite
Message (10..End)

The Message to be shown. This must be an ASCII based string. All unicode characters must be escaped.

App to Device Notification Transmission

As the name says, this transmission is sent from App to Remote Device, to notify of an event or deliver requested data. If the notification has no specific data, the delimiter is on position 9.

Byte-Index Description Type
8 Notification Type Single char
9 .. Notification Data Notification Specific
.. End Delimiter <CR> Char
Notification Type

The type of the notification

Value Description Payload Data
0 Reserved - Do not use None
1 Property-Loading-Complete Notification See below
2 Time Request Response See below
3 User navigated to Property Page Notification None
4 User navigated to DeviceMain-Page None
5 Language Request Response See below
6 Factory Reset Command None
7 Device re-connected Notification See below
8 Reserved - do not use None
9 Date Request Response See below
a UI-Mode Info Request Response See below
b User navigated to DeviceSettings-Page None
Property Loading Complete Notification

When the initial property loading is done, this notification is sent.

Value Description
0 Property Loaded from Device
1 Property Loaded from Cache
Time request response

This Notification is sent in response to a time request command.

Byte Index Description Type
9 Hour Value Dual hex Char
10 Hour Value Dual hex Char
11 Minute Value Dual hex Char
12 Minute Value Dual hex Char
13 Seconds Value Dual hex Char
14 Seconds Value Dual hex Char
15 Delimiter <CR> Char
User navigated to Property-Page Notification

This Notification is sent when the app user navigated to a complex property page. Field (2:3) of the transmission identifies the property index to which was navigated.

User navigated to DeviceMain-Page

This Notification is sent when the app user navigated back to the DeviceMain-Page (from a complex property page).

Language Request Response

This Notification is sent in response to a language request command.

Byte Index Description Type
9 Language ID - ISO 639-1 Dual Char
10 Language ID - ISO 639-1 Dual Char
15 Delimiter <CR> Char
Factory Reset Command

This Command is sent if the app-user presses the factory reset button on the DeviceSettingsPage.

Device re-connected Notification

If the device was connected and the user has left the app without closing the device, the connection will be suspended. When the user returns, the connection will be recoverd, but some properties or property-states may have changed, so if this notification is received it's a chance to update the changes.

Date request response

This Notification is sent in response to a date request command.

Byte Index Description Type
9 Day Value Dual hex Char
10 Day Value Dual hex Char
11 Month Value Dual hex Char
12 Month Value Dual hex Char
13 Year Value Quad hex Char
14 Year Value Quad hex Char
15 Year Value Quad hex Char
16 Year Value Quad hex Char
17 Delimiter <CR> Char
UI-Mode Info Request Response

This Notification is sent in response to a UI-Mode Info request command. Byte 9 identifies the current UI-Mode:

Value Description
0 Day Mode
1 Night Mode
Additional Info