Helper Classes

API Reference

DeviceBindingController
PinStorageController
RGBControl
Convert

DeviceBindingController

Description:

The DeviceBindingController can be used to handle enable-, release- and authentication-binding transmissions and the necessary permanent storage of the binding data. The controller is a singleton instance and can be accessed via the 'DeviceBindingController' acessor keyword. An implementation is only necessary if auto-handling of device-binding is not activated. More Info to DeviceBinding...

  		
/**
 * Access the binding controller helper API
 * 
 */
#define DeviceBindingController (*BindingController::GetInstance())

This helper class is also the logic that is working in the background when auto-handling of the device-binding is enabled. The controller interface has only two methods:

  		
// base functionality
BindingResponseType handleBindingTransmission(BindingTransmissionTypes bType, const String& key);

// fetch required status
bool isBindingRequired();

handleBindingTransmission

This method can be used to implement the whole functionality required for device binding. It takes the parameter carried in a binding transmission from app to device and returns the appropriate value to construct a binding response back to the app. This method also stores the key and the required parameter to flash.

Arguments:

bType - The binding transmission purpose (enable, release, authenticate. Type: BindingTransmissionTypes

key - The binding key. Only required for enable and authenticate transmissions. If this is a release transmission the key could be empty.

Return Value:

BindingResponseType - The appropriate response type for the BindingTransmissionType.

isBindingRequired

This method can be used to fetch the required status of device binding.

Return Value:

bool - Determines if binding is required or not.

Usage:

This is an example implementation how to handle binding transmission with the DeviceBindingController. The controller takes the arguments of the callback method onBindingTransmissionReceived of the ILaroomyAppCallback. It executes the necessary steps and returns the appropriate result.

  		
// define the callback for the remote app-user events
class RemoteEvents : public ILaroomyAppCallback
{
public:
    // handle binding transmissions (here we use the binding-controller which implements the whole functionality)
    BindingResponseType onBindingTransmissionReceived(BindingTransmissionTypes bType, const String &key) override
    {
        /*
            When implementing the device-binding this callback-method is invoked on three cases:

             - binding is enabled by the user
             - binding is released by the user
             - an authentication request is done during the connection process

            All cases must be handled and the appropriate value must be returned. (BindingResponseType)
            If this method is not overwritten and auto-handling of the device-binding is set to false,
            the app reports that device binding is not supported.

            Here the DeviceBindingContoller class is used to implement the whole functionality.
        */
        return DeviceBindingController.handleBindingTransmission(bType, key);
    }
};

When the program is started the required parameter must be loaded and passed to the LaRoomy Api.

  		
void setup()
{
    /* other setup */
    
    LaRoomyApi.setDeviceBindingAuthenticationRequired(
        DeviceBindingController.isBindingRequired()
    );    
    
    /* other setup */
};

PinStorageController

Description:

The PinStorageController can be used to save and load data to/from non-volatile memory to keep the pin for a UnlockControl property. It is a singleton instance and can be used only for one UnlockControl property. It can be accessed via the 'PinStorageController' accessor.

  		
/**
 * Access the Pin-Storage helper API.
 */
#define PinStorageController    (*UnlockControlPinStorageController::GetInstance())

The controller interface has only two methods:

  		
    /**
     * This methods loads the pin from flash storage,
     * or returns the default pin '12345' if no pin was saved before.
     */
    String loadPin();

    /**
     * This method saves the pin to flash storage.
     */
    bool savePin(const String& pin);

loadPin

This method loads the pin from flash storage or returns the default pin '12345' if no pin was saved before.

Return Value:

String - The previously saved pin or the default value.

savePin

This method saves the pin to flash storage.

Arguments:

pin - The pin to save. Please note that the pin is limited to 10 characters.

Return Value:

bool - Returns true if the pin has a valid format and the operation succeeded, false otherwise.

Usage:

The method savePin is normally used in the UnlockControlStateChanged callback method. If the user has changed the pin, this callback method is called in pin-change-mode. The pin must be saved to non volatile memory to access it later, even if the power was down.

  		
// define the callback for the remote app-user events
class RemoteEvents : public ILaroomyAppCallback
{
public:
    // catch the state change of the unlock control property
    void onUnlockControlStateChanged(cID unlockControlID, const UnlockControlState &state) override
    {
        // in unlock mode, lock or unlock whatever is to be unlocked
        if (state.mode == UnlockControlModes::UNLOCK_MODE)
        {
            if (state.unlocked)
            {
                // unlock
            }
            else
            {
				// lock
            }
        }
        else if (state.mode == UnlockControlModes::PIN_CHANGE_MODE)
        {
            // this is pin change mode, save the pin ..
            if (PinStorageController.savePin(state.pin))
            {
                // pin successful saved
            }
        }
    }
};

When the program is started, the pin must be loaded and passed to the state of the UnlockControl property.

  		
void setup()
{
    /* other setup */
    
    // create the unlock control property
    UnlockControl uc;
    uc.imageID = LaRoomyImages::UNLOCK_CONTROL_030;
    uc.unlockControlDescription = "Unlock";
    uc.unlockControlID = MY_UNLOCK_CONTROL;

    /**
     * Load the previously saved pin from flash or set a default pin if it wasn't saved before.
     */
    uc.unlockControlState.pin = PinStorageController.loadPin();
    
    // add the property
    LaRoomyApi.addDeviceProperty(uc);
    
    /* other setup */
};

RGBControl

Description:

The RGBControl class can be used to control RGB light output. It works in conjunction with the RGBSelector property and does support all functionalities which are adjustable. The RGBControl class has the following methods:

  		
class RGBControl {
public:
    RGBControl(pin_size_t RedPin, pin_size_t GreenPin, pin_size_t BluePin);

    void begin();
    
    void end();
    
    void off();
    
    void setFadeDelayValue(unsigned int fadeDelay);
    
    void setCustomColorSelection(ColorCollection& colorSel);
    
    void applyStateChange(const RGBSelectorState& state);
    
    void changeRGBColor(uint8_t red, uint8_t green, uint8_t blue, RGBTransitionType tType = RGBTransitionType::SOFT_TRANSITION);
    void changeRGBColor(PCOLOR c)
    
    void changeRGBProgram(RGBColorTransitionProgram program, RGBTransitionType tType);
    
    void onLoop();
};

RGBControl constructor

Creates the RGBControl object.

Arguments:

RedPin - The output pin for the red part of the color.

GreenPin - The output pin for the green part of the color.

BluePin - The output pin for the blue part of the color.

begin

Begins with the rgb processing. It initalizes the pin mode and the output on the pins defined in the constructor.

end

Stops the rgb processing. Do not use this method to disable output when the class should be used again later. In this case off() must be called.

off

program - The program(speed) to execute. Type: RGBColorTransitionProgram

tType - The type of transition. Type: RGBTransitionType

onLoop

This method must be implemented in the main loop and called periodically to ensure a fluent fading and internal processing.

Usage:

Create a RGBControl object:

  		
// define the pins for rgb output:
#define RED_PIN 10
#define GREEN_PIN 9
#define BLUE_PIN 6

// create the RGB control object
RGBControl rgbControl(RED_PIN, GREEN_PIN, BLUE_PIN);

Implement the control for the callback method to handle RGBSelector state changes:

  		
// define the callback for the remote app-user events
class RemoteEvents : public ILaroomyAppCallback
{
public:
    // receive rgb state notifications
    void onRGBSelectorStateChanged(cID rgbSelectorID, const RGBSelectorState &state) override
    {
        // use the rgb helper to control the colors
        rgbControl.applyStateChange(state);
    }
};

Start the RGBControl object:

  		
void setup()
{
    // put your setup code here, to run once:
    
    /* other setup */
    
    // set the callback handler for remote events
    LaRoomyApi.setCallbackInterface(
        dynamic_cast<ILaroomyAppCallback *>(
            new RemoteEvents()));    
    
    /* other setup */
    
    // begin rgb control
    rgbControl.begin();    

}

Call the 'onLoop' method periodically:

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

    LaRoomyApi.onLoop();

    // handle rgb control state changes
    rgbControl.onLoop();
}

Define a custom color selction for the transition program and add it. Here the Colors class is used to add some pre-defined colors.

  		
// new color collection
ColorCollection colorCollection;        

// use the Colors class to add other colors
colorCollection.AddItem(Colors::OrangeRed);
colorCollection.AddItem(Colors::SeaGreen);
colorCollection.AddItem(Colors::Turquoise);
colorCollection.AddItem(Colors::GreenYellow);
colorCollection.AddItem(Colors::PaleRed);
colorCollection.AddItem(Colors::Mint);
colorCollection.AddItem(Colors::Gold);
colorCollection.AddItem(Colors::YellowGreen);

// or add fully custom colors
COLOR col;
col.redPart = 56;
col.greenPart = 232;
col.bluePart = 127;

colorCollection.AddItem(col);

// pass the new color collection to the rgb helper
rgbControl.setCustomColorSelection(colorCollection);

Convert

Description:

The Convert class provides some methods to execute conversion of data. All methods of the class are static and can be called without instantiation. Most of the methods are intended for internal usage. An important part is the 'escapeNonAsciiCharacters' method. It could be used to convert a string with non-ascii characters in a transmittable format.

  		
class Convert {
public:
	static void u8BitValueToHexTwoCharBuffer(uint8_t toConvert, char* buffer_out);
    static unsigned int x2CharHexValueToU8BitValue(char left, char right);
    static void s16BitValueToHex4CharBuffer(int16_t toConvert, char* buffer_out);
    static int16_t x4CharHexValueToSigned16BitValue(char hl, char hr, char ll, char lr);
    static uint16_t x4CharHexValueToUnsigned16BitValue(char hl, char hr, char ll, char lr);
    static char uIntValToHexChar(unsigned int val);
    static unsigned int hexCharToUIntVal(char h);
    static char numToChar(unsigned int num);
    static unsigned int charToNum(char l);

	static String escapeNonAsciiCharacters(const wchar_t* wStr);
};

u8BitValueToHexTwoCharBuffer

Converts a unsigned 8bit parameter in a hexadecimal 2-char string.

Arguments:

toConvert - The parameter to convert.

buffer_out - The buffer to receive the mini-string. It must have at least two fields to receive the characters. The out string is not zero terminated, the method only writes the two character.

x2CharHexValueToU8BitValue

Converts a hexadecimal two-character string in a respective unsigned 8-bit value.

Arguments:

left - The left character of the hex string.

right - The right character of the hex string.

Return Value:

unsigned int - The converted value. Even if the return value is larger than 8bit, only the first 8 bit of the parameter are used.

s16BitValueToHex4CharBuffer

Converts a signed 16bit parameter in a hexadecimal 4-char string.

Arguments:

toConvert - The parameter to convert.

buffer_out - The buffer to receive the string. It must have at least four fields to receive the characters. The out string is not zero terminated, the method only writes the four character.

x4CharHexValueToSigned16BitValue

Converts a hexadecimal four-character string in a respective signed 16-bit value.

Arguments:

hl - The left character of the hibyte.

hr - The right character of the hibyte.

ll - The left character of the lobyte.

lr - The right character of the lobyte.

Return Value:

int16_t - The converted value.

x4CharHexValueToUnsigned16BitValue

Converts a hexadecimal four-character string in a respective unsigned 16-bit value.

Arguments:

hl - The left character of the hibyte.

hr - The right character of the hibyte.

ll - The left character of the lobyte.

wStr - The wide string to convert.

Return Value:

String - The compatible string.

Usage:

In the following example the text resources of a OptionSelector property must be provided in german language, this includes some non-ASCII characters. Here the Convert class is used to create a compatible string:

  		
  OptionSelector os;
  os.optionSelectorID = MY_OPTION_SELECTOR_ID;
  
  /* ... */
  
  os.optionSelectorDescription =
      Convert::escapeNonAsciiCharacters(L"Option wählen:"); // ä is not a valid ascii char
  
  /* ... */
  
  os.addOption(
      Convert::escapeNonAsciiCharacters(L"Fünf") // ü is not a valid ascii char
  );
  os.addOption(
      Convert::escapeNonAsciiCharacters(L"Maß") // ß is not a valid ascii char
  );  
  
  /* ... */
  
  LaRoomyApi.addDeviceProperty(os);

Do not forget to use 'L' literal in front of the string used as argument for the escape method to declare the string as wide string.