Get Started

General Info

The LaRoomy Api is a framework made to easily add bluetooth remote control functionality to your embedded project. The framework operates in conjunction with the LaRoomy App. It takes responsibility for the transmission, control and storage of the necessary data. All you have to do is to implement the project-specific logic related to your intended firmware design.

Remote devices have capablilities. They are built to process one or more task(s). In the concept of the LaRoomy remote control system these capabilities are called a Device-Property.

Device-Properties can be created and added with the LaRoomy Api. When the LaRoomy App connects to the remote device, it performs a Device-Property-Request to fetch the capablilities of the remote device and displays customized control elements inside of the app for all defined Device-Properties.

Each Property has a Property-State. The state is the data which is controlable within the app and is transmitted to the remote device. Property-States can be simple or complex. So Device-Properties are divided in Simple-Properties (Device-Properties with simple state) and Complex-Properties (Device-Properties with complex state). All Simple-Device-Property -States are based on an 8bit value. Complex-Device-Properties have a larger state with varying data sizes based on the type of the Property. Simple Properties will be displayed beneath each other on the Device-Main-Page of the app, whereas Complex-Properties got an own page. Details to the navigation of pages are shown below.


List of Device Properties

This is only a functional description of the Device-Properties. For an insight on how the Device-Properties will look like in the app, visit the LaRoomy App Website.

Device-Property Description Type
Button Property A simple Button is created in the app. If the user clicks on it, a simple impuls will be sent. The Button-Property has no usable state. Simple
Switch Property A simple Switch is created in the app. The Switch has a state which can be On(1) or Off(0). If the user clicks on it, the current state of the switch will be transmitted. Simple
Level-Selector Property A slider control is created and the user can select a level. If the level changes in the app a state transmission is sent. The state value can range between 0 and 255. Simple
Level-Indicator Property This Property displays a level to the user. The Property-State is the level and can range from 0 to 255. This Property is only a data-viewer and not executable by the user. Simple
Text-Display Property This Property displays a message or information to the user. This Property is only a data-viewer and not executable by the user. The Property-State is not used. Simple
Option-Selector Property With this Property a user can select an option out of an option-list. The Property-State is the index of the current selected option. A transmission is sent if the selected index changes. Simple
RGB-Selector Property With this Property a user can set up data which could be used to control an RGB Light. If the user interacts with the Property, a Complex-Property-State-Update is sent to the remote device. Complex
Extended Level-Selector Property With this Property a user can select a level. The selector has a customizable scale and can carry larger value than the simple Level-Selector. A Complex-State-Update is sent on interaction. Complex
Time-Selector Property With this Property a user can select a simple time. A Complex-State-Update is sent on interaction. Complex
Time-Frame-Selector Property With this Property a user can select two time values. A start time and an end time. A Complex-State-Update is sent on interaction. Complex
Date-Selector Property With this Property a user can select a date. A Complex-State-Update is sent on interaction. Complex
Unlock-Control Property With this Property the user can enter a pin to unlock something. A Complex-State-Update is sent on interaction. Complex
Navigator-Control Property The user can control somthing with direction buttons. A Complex-State-Update is sent on interaction. Complex
Bar-Graph Property With this Property data can be visualized in a Bar-Graph. This Property is only a data-viewer and not executable by the user. Complex
Line-Graph Property With this Property data can be visualized in a Line-Graph. This Property is only a data-viewer and not executable by the user. Complex
String-Interrogator Property With this Property the user has the ability to send string data to the device. Or the device can request string data from the user. A Complex-State-Update is sent on interaction. Complex
Text-List-Presenter Property Messages or Notifications can be displayed in list like a log. This Property is only a data-viewer and not executable by the user. Complex
Button Property

A simple Button is created in the app. If the user clicks on it, a simple impuls will be sent. The Button-Property has no usable state.

Switch Property

A simple Switch is created in the app. The Switch has a state which can be On(1) or Off(0). If the user clicks on it, the current state of the switch will be transmitted.

Level Selector Property

A slider control is created and the user can select a level. If the level changes in the app a state transmission is sent. The state value can range between 0 and 255.

Level Indicator Property

This Property displays a level to the user. The Property-State is the level and can range from 0 to 255. This Property is only a data-viewer and not executable by the user.

Text Display Property

This Property displays a message or information to the user. This Property is only a data-viewer and not executable by the user. The Property-State is not used.

Option Selector Property

With this Property a user can select an option out of an option-list. The Property-State is the index of the current selected option. A transmission is sent if the selected index changes.

RGB Selector Property

With this Property a user can set up data which could be used to control an RGB Light. If the user interacts with the Property, a Complex-Property-State-Update is sent to the remote device.

Extended Level Selector Property

With this Property a user can select a level. The selector has a customizable scale and can carry larger value than the simple Level-Selector. A Complex-State-Update is sent on interaction.

Time Selector Property

With this Property a user can select a simple time. A Complex-State-Update is sent on interaction.

Time Frame Selector Property

With this Property a user can select two time values. A start time and an end time. A Complex-State-Update is sent on interaction.

Date Selector Property

With this Property a user can select a date. A Complex-State-Update is sent on interaction.

Unlock Control Property

With this Property the user can enter a pin to unlock something. A Complex-State-Update is sent on interaction.

Navigator Control Property

The user can control somthing with direction buttons. A Complex-State-Update is sent on interaction.

Bar Graph Property

With this Property data can be visualized in a Bar-Graph. This Property is only a data-viewer and not executable by the user.

Line Graph Property

With this Property data can be visualized in a Line-Graph. This Property is only a data-viewer and not executable by the user.

String Interrogator Property

With this Property the user has the ability to send string data to the device. Or the device can request string data from the user. A Complex-State-Update is sent on interaction.

Text List Presenter Property

Messages or Notifications can be displayed in list like a log. This Property is only a data-viewer and not executable by the user.

Functional Concept

When the connection to the device is successfully established, the app has to fetch all necessary data from the remote device to show all required control elements. Therefore the app sends requests for data it needs. The device must always respond to this requests in specific time period, otherwise the device is considered as offline and the connection is terminated. Note that the user of the app can reload the whole property data, so all requests can happen at any time, not only when the connection process is ongoing. The first transmission that is sent is an 'Init-Request'. The remote device must respond with an 'Init-Response'. This transmission contains general information of the remote device.

A part of the 'Init-Response' is the information if the device requires a Device-Binding-Authentication. If this is the case, an 'Authentication-Request' is sent to the remote device. If the device accepts the transmitted Binding-Key, the app proceeds with the next step. If no Binding-Key is required, this step is skipped.
When the Init and Authentication is finished, the app sends the first 'Property-Request'. This transmission contains the index of requested property. The remote device must answer with a 'Property Response' containing data to constuct the property element. After that, the app increases the index and requests the data for the next property element. This loop will be repeated until the property amount defined in the 'Init-String' is reached.
The next step is the retrieval of the group elements. The scheme is the same as in the property loop. The app sends a 'Group-Request' and the remote device must answer with a 'Group-Response'. When the amount of groups has reached the value of the group-count paramter defined in the 'Init-String', the group loop is finished.
Now all property and group data is retrieved. The Simple-Property-States are included in the Property-Response, but the Complex-Property-States are not. So the app sends 'Complex-Property-State-Requests' for all complex properties to the remote device, an it has to send a 'Complex-Property-State-Response' for all requests.

Note that the Propertyies and Groups are shown before the 'Complex-Property-State-Loop' is started. When the group loop is finished, the necessary data to construct the user interface are complete and the DeviceMainPage is shown. The complex property states are retrieved in a background task. Navigating to a Complex-Property-Page is only possible if the complex property states are fully retrieved.

Sometimes a complete update of all Propert-States is necessary. A scenario where this makes sense is for example when the connection was suspended and is later resumed. In this case the previously explained loading process is not executed. If the properties and groups are static and are the same as before but the states may have changed, an update of all property states can be executed. If this is done, the app starts with an update cycle of the simple property states.

When the states for all properties with simple state are retrieved, the app starts to request the states for all Complex-Properties.

The following illustration shows the navigation storyboard of the app.

On the MainPage the added devices are displayed in a list. If a device is selected, the LoadingPage is shown and the connection process is initiated. When the connetion succeeds and the device-properties are loaded, the app navigates to the DeviceMainPage. If there are complex properties in the list on the DeviceMainPage and the user clicks on this property element the app navigates to the respective ComplexPropertyPage.