ACS BACI sync smart bulb

BACI basics

In this section we will modify our smart bulb ACS component in order to make it BACI compliant. BACI is a control interface specification we use for ACS at ALMA. For more details this document is available. There is also another useful tutorial here. BACI is only available for C++ components.

From these different sources we can take some guidelines:

• A Component is a CORBA object that corresponds to a conceptually self contained  entity: this can be a physical device or a business component that implements certain business logic.
• A Characteristic is a data item that is considered static. It can change by context but not by the controller entity.
  
• Each component has a number of component properties that are controlled, e.g. electric current, status, position, etc.
• A property is a typed changeable value in a context. Properties are represented by interfaces. Depending on the nature of the property, the value that the property interface encapsulates can be either read (by using property's accessor methods), set (by using property's mutator methods) or both. In this regard properties can be flagged as readable, writable or read-writable.
  
• An action is a command with the following properties:
  • It is issued asynchronously.
  • When the command finishes the execution, a notification is sent from the remote object to the object that issued the command; this notification must contain the description of the command execution status (successful or failure, reason for possible failure, timestamp).
  • The action has a well defined execution path, i.e. after executing the command, it must complete its execution either with an error condition or along exactly one execution path that leads to successful completion; the action must complete the execution by itself (e.g. it is illegal to define an action, which when invoked, executes as long as the component containing it exists; the action must terminate on its own).
  • The action termination state (either successful or in error condition) is reported through an universal notification (notification of which the syntax will be defined by this document).
  • An action is timed there exists a mechanism by which the remote object can obtain the timeout interval used by the caller; if the action is not before the timeout interval, the remote object must inform the caller that action is still in progress.

• When we are defining actions, we must write its arguments and what it returns. Every asynchronous action must have "in ACS::CBvoid cb, in ACS:CBDescIn desc". Note that beside arguments there is also a word "in". Here is short explanation of all possibilities (from Advance CORBA programming with C++):

  • in – the in attribute indicates that the parameter is sent from client to the server
  • out – the out attribute indicates that the parameter is sent from the server to the client
  • inout – The inout attribute indicates a parameter that is initialized by the client and sent to the server.

So, in short:

• Each component can access one and only one controlled device.
• Characteristics are static variables in the component. They can be read by the controller, but can be set only by the component, depending on context. They are monitoring points.
• Properties are variables set by the controller. They are control points.
• Getters for characteristics are synchronous.
• It is recommended to implement asynchronous accessors to properties, but not mandatory.

Modifications needed

To make our component a BACI compliant code, we must perform the following modifications:

1. A single component cannot control multiple physical devices. The component must control a unique physical device, so it must have a "device_id" characteristic, instead of passing it as a parameter.
2. The "api_region", "api_key", and "api_secret" parameters must also be characteristics of the component, since they are static data as well.
3. Actions "turnOn" and "turnOff" will be implemented asynchronously for simplicity. In another section we will implement a asynchronous component.

Example BACI component template

working_dir: /home/francisco/workspace
prefix: ACSIOT
module: acsiot
component_name: TuyaBulbBaci
functions:
  - 'void turnOn(in string api_region, in string api_key, in string api_secret)'
  - 'void turnOff(in string api_region, in string api_key, in string api_secret)'
  - 'ACS::ROboolean getStatus()'
  - 'readonly attribute ACS::ROboolean status'

Example IDL for a BACI compliant smart bulb ACS component

#ifndef _TUYABULBBACI_IDL_
#define _TUYABULBBACI_IDL_
 
#pragma prefix "ACSIOT"
 
#include <baci.idl>
 
module acsiot {
    interface TuyaBulbBaci : ACS::CharacteristicComponent {
        void turnOn(in string api_region, in string api_key, in string api_secret);
        void turnOff(in string api_region, in string api_key, in string api_secret);
        ACS::ROboolean getStatus();
        readonly attribute ACS::ROboolean status;
    };
};

#endif