LaRoomy Api Interface

Description

The LaRoomyApi class object is the main access point to interact with the framework. Actually this object is only an instance accessor for the real Interface-Class: LaRoomyAppImplementation. 

  	
/**
 * Access the LaRoomy API
 * 
 */
#define	LaRoomyApi	(*LaRoomyAppImplementation::GetInstance())

This interface provides methods for the configuration of the interface and the interaction with the component. The object is a singleton instance and cannot be instantiated directly. By accessing the object it is automatically created. The lifetime ends when end() is called.

Usage

At first, the appropriate header for the platform must be included: 

  	
// Espressif32 Platform Header:
#include <LaRoomyApi_Esp32.h>

// Atmel SAM Platform Header:
#include <LaRoomyApi_AtSAM.h>

// STM32 Platform Header:
#include <LaRoomyApi_STM32.h>

// Nordic nRF52 Platform Header:
#include <LaRoomyApi_nRF52.h>

The first call on the object is begin(). After that, basic configuring must be done, this includes the setup of the callback(s). When configured, Device-Properties and/or Device-Property-Groups can be added. Finally run() must be called to apply the setup and start the bluetooth functionality. 

  	
void setup()
{
    // put your setup code here, to run once:

	/* other setup ... */
    
    // begin
    LaRoomyApi.begin();
    
    /* Basic configuring ... */

    // set the bluetooth name
    LaRoomyApi.setBluetoothName("Nano 33 Ble");

    // set device image
    LaRoomyApi.setDeviceImage(LaRoomyImages::ACCESS_CONTROL_025);

    // set the callback handler for remote events
    LaRoomyApi.setCallbackInterface(
        dynamic_cast<ILaroomyAppCallback *>(
            new RemoteEvents()));

    /* Create and add properties/groups ... */
    
    // on the end, call run to apply the setup and to start bluetooth advertising
    LaRoomyApi.run();
}

The Atmel SAM and Nordic nRF52 Platform requires an implementation of the onLoop() method inside the main loop to check for events permanently. 

  	
void loop()
{
    // put your main code here, to run repeatedly:

    LaRoomyApi.onLoop();
    
    /* do other stuff ... */
}

API Reference

This is a list of all available methods that can be called on the LaRoomyApi object:


begin

  		
void begin();

Must be called before using the Interface.

end

  		
void end();

This method stops bluetooth advertising, clears all properties and groups and deletes the interface object.

run

  		
void run();

When setup is done on the LaRoomy Api, this method must be called to apply the setup and start bluetooth advertising. Some settings on the interface object cannot be changed anymore after the call of this method.

onLoop

  		
void onLoop();

The onLoop method must be called periodically in the main loop to ensure the workload processing. This is only required on some platforms. If it is not required, the LaRoomyApi object does not contain this method.

addDeviceProperty

  		
void addDeviceProperty(const DeviceProperty& p);

With this method a Device-Property can be added to the LaRoomy Api. Note that this method can take all Property-Classes as an argument, since the DeviceProperty Class has constuctors for all classes.

Arguments:

p - The property element to add. Type: DeviceProperty

addDevicePropertyGroup

  		
void addDevicePropertyGroup(const DevicePropertyGroup& g);

With this method a Device-Property-Group can be added to the LaRoomy Api. Note that the group must contain property elements otherwise the group will discarded.

Arguments:

g - The group element to add. Type: DevicePropertyGroup

insertProperty

  		
void insertProperty(cID insertAfter, const DeviceProperty& p);

Use this method to insert a property at a desired position. This works at any time, even if the device is connected.

Arguments:

insertAfter - The ID of the element before the insert-position. To insert at the first position use the definition INSERT_FIRST. To insert at last position use INSERT_LAST.

p - The property element to insert. Type: DeviceProperty

insertPropertyInGroup

  		
void insertPropertyInGroup(cID insertAfter, cID groupID, const DeviceProperty& p);

Use this method to insert a property in a property group at a desired position. This works at any time, even if the device is connected.

Arguments:

insertAfter - The ID of the element before the insert-position. The element must be part of the group with the given ID. To insert at the first position inside of the group use the definition INSERT_FIRST. To insert at last position use INSERT_LAST.

groupID - The ID of the group in which to insert.

p - The property element to insert. Type: DeviceProperty

updateDeviceProperty

  		
void updateDeviceProperty(const DeviceProperty& p);

Updates an existing property element. If the device is connected to the app, an update transmission will be sent.

Arguments:

p - The property element to update. Type: DeviceProperty

getProperty

  		
DeviceProperty getProperty(cID propertyID);

To retrieve an existing property element this method can be used. If the element with the ID was not found, an empty object will be returned.

Arguments:

propertyID - The ID of the element to retrieve.

Return Value:

DeviceProperty

removeProperty

  		
void removeProperty(cID propertyID);

Removes a property element. This could be done at any time, even if the device is connected. Please note that if the property element is part of a group and the property count of the group reaches 0, the group will be also deleted.

Arguments:

propertyID - The ID of the property element to remove.

removePropertyGroup

  		
void removePropertyGroup(cID groupID);

Removes a group element and all it's properties.

Arguments:

groupID - The ID of the group element to remove.

enableProperty

  		
void enableProperty(cID propertyID);

Enables a property element if it was previously disabled. If the app is connected, an enable transmission will be sent. The element will be drawn in normal state and accepts user input.

Arguments:

propertyID - The ID of the property element to enable.

disableProperty

  		
void disableProperty(cID propertyID);

Disables a property element. If the app is connected, a disable transmission will be sent. The element is grayed out and does not accept user input.

Arguments:

propertyID - The ID of the property element to disable.

clearAllPropertiesAndGroups

  		
void clearAllPropertiesAndGroups();

With this method all previously added properties and groups are deleted. This should not be done while the app is connected.

sendUserMessage

  		
void sendUserMessage(UserMessageType type, UserMessageHoldingPeriod period, const String& message);

If the device is connected to the app, a notification will be displayed to the user. If the device is disconnected, the call of this method has no effect.

Arguments:

type - The severity type of the message. Type: UserMessageType

period - The display time for the message. If the period is elapsed, the message will be hidden. Type: UserMessageHoldingPeriod

message - The message to display.

sendTimeRequest

  		
void sendTimeRequest();

A time request will be sent to the app. To get the result, listen to the onTimeRequestResponse method of the LaRoomyAppCallback.

sendDateRequest

  		
void sendDateRequest();

A date request will be sent to the app. To get the result, listen to the onDateRequestResponse method of the LaRoomyAppCallback.

sendPropertyReloadCommand

  		
void sendPropertyReloadCommand();

A reload command will be sent to the app. This forces the app to reinitiate the complete init and property loading process.

sendPropertyToCacheCommand

  		
void sendPropertyToCacheCommand();

This command forces the app to save the current property and group construct to cache. Please note that this will only work if property caching is enabled on the device and the user has granted property caching in app settings.

sendLanguageRequest

  		
void sendLanguageRequest();

A language request will be sent to the app. To get the result, listen to the onLanguageRequestResponse method of the LaRoomyAppCallback.

sendRefreshAllStatesCommand

  		
void sendRefreshAllStatesCommand();

This command forces the app to refresh all property states through a simple and complex property state loop.

sendNavBackToDeviceMainCommand

  		
void sendNavBackToDeviceMainCommand();

This method triggers a back-navigation if the app user has navigated to a property-sub-page or the device-settings-page. Note that this will not work in stand-alone-mode. To determine the navigational state of the app listen to the appropriate methods of the LaRoomyAppCallback or check the current opened page with the getCurrentOpenedPropertyPageID method.

sendCloseDeviceCommand

  		
void sendCloseDeviceCommand();

The current connection to the device will be closed and the app goes back to the start-page.

sendUIModeInfoRequest

  		
void sendUIModeInfoRequest();

Request additional information of the current UI Mode of the app. To get the result, listen to the onUIModeRequestResponse method of the LaRoomyAppCallback.

addTextListPresenterElement

  		
void addTextListPresenterElement(cID textListPresenterID, TextListPresenterElementType type, const String& elementText);

When a TextListPresenter property was added, this method can be used to add an element to the presenter. Please note that this only works if the device is connected to the app.

Arguments:

textListPresenterID - The ID of the TextListPresenter property to which the element should be added.

type - The type of the element to add. Type: TextListPresenterElementType

elementText - The text of the element.

clearTextListPresenterContent

  		
void clearTextListPresenterContent(cID textListPresenterID);

Removes all elements from the TextListPresenter stack. Note that this only works if the device is connected to the app.

Arguments:

textListPresenterID - The ID of the TextListPresenter property to clear.

setCallbackInterface

  		
void setCallbackInterface(ILaroomyAppCallback* callback);

Insert a reference to a callback interface to receive events from the LaRoomy Api. More Info..

Arguments:

callback - Pointer to a class which inherits from the ILaRoomyAppCallback interface.

setDescriptionCallback

  		
void setDescriptionCallback(IElementDescriptionCallback* callback);

Insert a reference to a descriptor callback interface to provide language specific property descriptions. More Info..

Arguments:

callback - Pointer to a class which inherits from the IElementDescriptionCallback interface.

isConnected

  		
bool isConnected();

Read the current connection status.

Return Value:

Type: bool - true if connected or false otherwise

getCurrentOpenedPropertyPageID

  		
cID getCurrentOpenedPropertyPageID();

Use this method to determine the current navigational state of the app. This only works if the device is connected to the app.

Return Value:

Type: cID - If a complex property page is open the method returns the ID of the respective property element. If the DeviceMainPage is open, the return value is ID_DEVICE_MAIN_PAGE. If the method fails, the return value is zero.

checkIfPropertyExist

  		
bool checkIfPropertyExist(cID propertyID);

Use this method to determine if a property was previously added and exists on the property stack.

Arguments:

propertyID - The ID of the property element to search for.

Return Value:

Type: bool - true if the property exist or false otherwise

setPropertyCachingPermission

  		
void setPropertyCachingPermission(bool cp);

Enable or disable property caching for the device. Please note that proptery caching must also be enabled by the user in app settings for this to work.

Arguments

cp - true if caching should be permitted, false otherwise. The default value is: false

setDeviceBindingAuthenticationRequired

  		
void setDeviceBindingAuthenticationRequired(bool required);

Enable or disable DeviceBinding. If enabled the device requires a key to connect to. Note that DeviceBinding is enabled by the app, so this should only be set to true if it was previously enabled from app side and a key was transmitted and saved. If auto-handling of DeviceBinding is enabled, this method must not be called. More Info to DeviceBinding..

Arguments:

required - true to enable DeviceBinding or false to disable. The default value is: false

setSerialMonitorEnabledState

  		
void setSerialMonitorEnabledState(bool state);

Enables or disables the output on the Serial interface. This is only for evaluation purposes and should remain disabled.

Arguments:

state - true to enable output or false to disable. The default value is: false

setStandAloneMode

  		
void setStandAloneMode(bool enable);

Enables or disables the standalone mode. Note that the standalone mode only works if a single property from complex type is added. More Info..

Arguments:

enable - true to enable the standalone mode or false to disable. The default value is: false

setServiceUUID

  		
void setServiceUUID(const String& sUUID);

Set the Bluetooth Service UUID. This must be done before run() is called.

Arguments:

sUUID - The UUID as String for the service.
The default value is: b47f725f-5fca-45b9-998f-f828388d044f

setTxCharacteristicUUID

  		
void setTxCharacteristicUUID(const String& cUUID);

Set the Bluetooth TX-Characteristic UUID. This must be done before run() is called.

Arguments:

cUUID - The UUID as String for the TX characteristic.
The default value is: 124c0402-da98-4d2b-8492-e712f8036997

setRxCharacteristicUUID

  		
void setRxCharacteristicUUID(String& cUUID);

Set the Bluetooth RX-Characteristic UUID. This must be done before run() is called.

Arguments:

cUUID - The UUID as String for the RX characteristic.
The default value is: 124c0402-da99-4d2b-8492-e712f8036997

setBluetoothName

  		
void setBluetoothName(const String& bName);

Set the Bluetooth-Name for the device. This must be done before run() is called.

Arguments:

bName - The name for the device.

setDeviceImage

  		
void setDeviceImage(LaRoomyImages img);

Set the image for the device. A hexadecimal appendix will be added to the Bluetooth-Name. This is the identification for the image in the device list. For a list of images click here.

Arguments:

img - The image of the device. Type: LaRoomyImages

enableAutoRefreshStates

  		
void enableAutoRefreshStates(bool enable);

Enable or disable the auto refresh function of the property states. This is enabled by default. It lets the Api decide when to refresh the states. A manual refresh command is also valid when auto-refresh is activated.

Arguments:

enable - true to enable or false to disable. The default value is: true

enableInternalBindingHandler

  		
void enableInternalBindingHandler(bool enable);

Enable or disable the internal Binding-Handler. If enabled the Api takes responsibility for whole binding process. More Info..

Arguments:

enable - true to enable or false to disable. The default value is: false

getSimplePropertyState

  		
unsigned int getSimplePropertyState(cID pID);

This method returns the Property-State of a Simple-Property.

Arguments:

pID - The ID of the property whose state is requested.

Return Value:

unsigned int - The requested PropertyState.

Complex Property State Getter Methods

The getter methods for the Complex-Property-States are explained here.

updateSimplePropertyState

  		
void updateSimplePropertyState(cID propertyID, unsigned int value);

Updates the Property-State of a simple property element.

Arguments:

propertyID - The ID of the property whose state to update.

value - The new state.

Complex Property State Update Methods

The update methods for the Complex-Property-States are explained here.

Fast Data Pipe Setter Methods

The Fast-Data-Pipe setter methods are explained here.