API Documentation

Objects

Root

To specify a root object of the user-written adapter, you must create a class that inherits from class Root:

from alphalogic_api.objects import Root
......
class MyRoot(Root):
    ......
class alphalogic_api.objects.Root

Root object inherits from Object. This kind of object is a child for the adapter service node. Root object is created automatically when starting the adapter instance.

Parameters:
  • host – hostname of the gRPC stub instance of the composite adapter
  • port – port of the gRPC stub instance of the composite adapter
join()

Wait until all threads within stub process terminate. This function provides an infinite communication loop between the adapter core and gRPC stub instance. Must be placed in the code of the adapter to keep it working till the process be stopped by the user or an error happens.

Object

To specify an adapter object (not Root object), create a class that inherits from the class Object:

from alphalogic_api.objects import Object
......
class Controller(Object):
    ......
class alphalogic_api.objects.Object(type_device, id_device, **kwargs)

Adapter object can have a number of interactions (parameters, commands, events) and run functions. All the declarations of the object interactions must be placed inside the Object class body. Each of them must have a unique name among instances of the same class.

children()

Get child objects

Return type:list of child Object
command(name)

Get command by name

Parameters:name – command name
Return type:Command
commands()

Return events of the object

Return type:list of Command
event(name)

Get event by name

Parameters:name – event name
Return type:Event #TODO
events()

Return events of the object

Return type:list of Event #TODO
handle_defaults_loaded(**kwargs)

Handler for configure Object after creation. Parameters, commands, events have already created.

handle_prepare_for_work()

Handler is executed before work of object Parameters, commands, events have already created.

parameter(name)

Get parameter by name

Parameters:name – parameter name
Return type:Parameter #TODO
parameters()

Return parameters of the object

Return type:list of Parameter #TODO
parent()

Get parent object

Return type:parent Object
root()

Get root object

Return type:Root

Parameter

You have to define parameter, depending on its value type:
ParameterBool, ParameterLong, ParameterDouble, ParameterDatetime, ParameterString

Example of parameter definition:

from alphalogic_api.objects import ParameterBool, ParameterLong, ParameterDouble, ParameterDatetime, ParameterString
...

message = ParameterString(default='Hello world!')

Example of setting and gettings value:

self.message.val = 'Me too'
self.param_str.val = self.message.val

Parameter arguments are optional.

Argument Description Default Value Possible Values
default Default parameter value
0 (ParameterLong)
False (ParameterBool)
0.0 (ParameterDouble)
0 (ParameterDatetime)
“” (ParameterString)
All the values of the
corresponding type are
allowed (for example,
a parameter of
ParameterDouble can
hold real numbers)
visible
A parameter type that
specifies its features
and visibility in the
Alphalogic Studio
Visible.runtime
Visible.runtime - used
to transfer data from
integrated device or
subsystem into
Alphalogic
Visible.setup - used to
configure adapter
object’s properties
Visible.hidden - used to
store some data that
must be hidden for
target user, e.g.
adapter license key
Visible.common - a
hybrid of
Visible.runtime and
Visible.setup
parameter types
providing combined
functions
access
A parameter access type
which specifies the
permitted and prohibited
uses of the parameter
Access.read_write
Access.read_write
Access.read_only
choices
Allows to set up a
predefined enumeration
of values for the
parameter
The enumeration can be
specified in one of two
different ways:
1) list of values of the
corresponding type in a
tuple as (value1,
value2, …, valueN)
2) list of enumeration
members in a tuple of
tuples as ((value1,
‘enum_name1’), (value2,
‘enum_name2’), …,
(value2, ‘enum_nameN’))

To build a value list for the parameter, it is required that both arguments ‘choices’ and ‘default’ are specified.

param_tmp = ParameterLong(visible=Visible.setup, access=Access.read_write, default=1, choices=((1, 'First'), (2, 'Second')))

Be careful to assign a value (not an enumeration member’s name) to ‘default’ argument if the ‘choices’ argument provides enumeration with descriptions:

param_tmp2 = ParameterBool(default=True, choices=((True, 'On'), (False, 'Off')))

Here is the definition of the class Parameter:

class alphalogic_api.objects.Parameter(*args, **kwargs)

Class Parameter inherits all data elements and methods from AbstractParameter.

Event

You have to define event, depending on its severity level:
TrivialEvent, MinorEvent, MajorEvent, CriticalEvent, BlockerEvent

To define an event with arguments, you must append a tuple of (argument name, argument type) pairs. The names of the arguments must be enclosed with single or double quotes.

Example of event definition:

alarm = MajorEvent(('where', unicode), ('when', datetime.datetime), ('why', long))
The possible value types of the event arguments are:
  • unicode – used for string data,
  • datetime.datetime – used for date and time,
  • long – for integer values,
  • float – to store real numbers,
  • bool – used for boolean values.

The function that triggers an event occurence (emit) can be passed with the event arguments as a tuple of name/value pairs, each argument name followed by an equal sign:

alarm.emit(where="Red Square, Moscow", when=datetime.datetime(2018, 12, 31), why=123456)

Python allows you to pass functions as a parameters to another functions. In the present case, function can be passed instead of the value for the event argument:

alarm.emit(where="Red Square, Moscow", when=datetime.datetime.utcnow(), why=123456)

Example of the event function without arguments:

alarm.emit()

Here is the definition of the class Event:

class alphalogic_api.objects.Event(priority, *args)

Class Event inherits inherits all data elements and methods from AbstractEvent.

Parameters:
  • priority – trivial, minor, major, critical or blocker
  • args – name/type pairs in a tuple of tuples (argument name, argument type)

Decorators

A decorator is any callable Python object that is used to modify a function, method or class definition. A decorator is passed the original object being defined and returns a modified object, which is then bound to the name in the definition. Decorators are used for creating class methods or static methods, adding function attributes, tracing, setting pre- and postconditions, etc. The @ special character is used to indicate a decorator.

Command

Here is the definition of the class Command:

class alphalogic_api.decorators.command

Use this decorator to create Command object.

Example 1:

# The command returns True every time
@command(result_type=bool)
def cmd_exception(self):
    # do smth
    return True

Example 2:

# The command has three arguments and returns 'where' argument value
@command(result_type=bool)
def cmd_alarm(self, where='here', when=datetime.datetime.now(), why=2):
    return where
Parameters:result_type – Command return type

Run functions ~~~ There is easy way to do some job periodicaly. You can define a lot of run functions in the root or object.

class alphalogic_api.decorators.run
This function is used to be called periodically by the gRPC process.
It can be defined inside the Object class body to implement some repeatable tasks like interrogation of the controller, modem, database, etc.
It is required to specify the necessary trigger period in seconds in the argument of the function.

Example:

# Called every 1 second.
# You can change period by changing 'period_one' parameter.

@run(period_one=1)
def run_one(self):
    self.counter.val += 1

Handlers

The handlers are executed when the corresponding condition occurs. There are three types of handlers which can be installed to control the workflow of the adapter before or after calling some functions:

1) Request on child objects of the adapter object:

def handle_get_available_children(self):
    return [
        (Controller, 'Controller'),
        (MyObject, 'MyObject')
    ]

You can define and implement this function in the object class to return an array of the child adapter objects. You must use the exact name of the handler as in the example above.

2) Request on deletion of the adapter object(s):

def handle_before_remove_device(self):
    do something

You can use this handler to do something before the adapter object will be deleted. You must use the exact name of the handler as in the example above.

3) Changing the value of the parameter:

def handle_after_set_double(node, parameter):
    node.log.info('double changed')
    node.after_set_value_test_event.emit(value=parameter.val)

param_double = ParameterDouble(default=2.3, callback=handle_after_set_double)

The handler will be invoked when the specified parameter is changed. In the example above, this means that the function handle_after_set_double will be called if param_double is changed. In the case of parameter changes, you can use whichever name of the handler function you like.

4) Handler for configure Object after creation by user

number = ParameterLong(visible=Visible.setup)
def handle_defaults_loaded(self):
    self.displayName.val = str(self.number.val)

5) Handler is executed before work of object

number = ParameterLong(visible=Visible.setup)
def handle_prepare_for_work(self):
    self.displayName.val = str(self.number.val)

Оbject lifetime

Created by user

  1. __init__. You can’t do anything with parameters, events, commands here.
  2. Create parameters, events, commands
  3. Accept values from __init__ kwargs. See Advanced using p.1.
  4. handle_defaults_loaded handle
  5. handle_prepare_for_work handle

Loaded from configuration

  1. __init__. You can’t do anything with parameters, events, commands here.
  2. Create parameters, events, commands
  3. handle_prepare_for_work handle

Removed by user

  1. handle_before_remove_device

Advanced using

1) Create a child object with predefault values:

class Controller(Object, DiagHelper):
    some_parameter_title = ParameterLong(default=0)

def handle_get_available_children(self):
    children = []  # return empty list if exception
    try:
        p = partial(Controller, some_parameter_title=0)
        p.cls = Controller
        children.append((p, 'Controller 0'))

        # You can set parameter values in
        p = partial(Controller, some_parameter_title=1, displayName=h['name'])
        p.cls = Controller
        children.append((p, 'Controller 1'))

    except Exception as err:
        log.error(err.message)
    return children

Handlers order example

1) Situation 1: User creates object

class Controller(Object):

    def __init__(self, type_device, id_device, **kwargs):
        super(Controller, self).__init__(type_device, id_device, **kwargs)
        # 1: Partial arguments in the kwargs

    def handle_defaults_loaded(self, **kwargs):
        # 2: Partial arguments in the kwargs

    def handle_prepare_for_work(self):
        # 3: Parameters, commands, events created and have default values

    def handle_before_remove_device(self):
        # remove object by user

2) Situation 2: Object has been loaded from configuration

class Controller(Object):

    def __init__(self, type_device, id_device, **kwargs):
        super(Controller, self).__init__(type_device, id_device, **kwargs)
        # 1: nothing in the kwargs

    def handle_defaults_loaded(self, **kwargs):
        # Not called

    def handle_prepare_for_work(self):
        # 2: Parameters, commands, events created.
        #    Values from configuration loaded.

Exceptions

class alphalogic_api.exceptions.IncorrectRPCRequest(msg)

This kind of exception occurs when there is an internal API error, possibly incorrect syntax of some function, or something else.

class alphalogic_api.exceptions.RequestError(msg)

Internal gRPC call error that occurs when the remote request processing has failed.

class alphalogic_api.exceptions.ComponentNotFound(msg)

API error that occurs if the name of the declared variable is missing, mismatched, or unidentifiable

class alphalogic_api.exceptions.Exit

A fatal exception that will trigger adapter instance to exit