Alphalogic API¶

The official library for creating the Alphalogic system adapter

Compatibility¶

The library is compatible with Alphalogic adapter versions since .0315

The recommended way to set your requirements in your setup.py or requirements.txt is:

# Protobuf
protobuf==3.6.0

# gRPC
grpcio==1.12.1
grpcio-tools==1.12.1

Installation¶

Install the alphalogic_api package with pip:

pip install alphalogic-api

Overview¶

Alphalogic adapter is program in alphalogic platform. One side’s adapter implements described programmed protocol or device(user code via the this library), and the other side is integrated in alphalogic platform.

Adapter has entities that represent objects(nodes), parameters, events, commands. Adapter is a tree of objects.

Object is a unit that has specific technical functions. Adapter has Root object is a root of tree. Other node inherits from class Object.

There are types of interactions with adapter: commands, parameters, and events.

Parameter

Corresponds to a current value of the system object’s property.

Event

Corresponds to a state that indicates what has happened with the system object

Command

A simple operation a system object can perform.

Example Usage¶

Create stub.py file in the Alphalogic adapter folder.

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

from alphalogic_api.attributes import Visible, Access
from alphalogic_api.objects import Root, Object
from alphalogic_api.objects import MajorEvent
from alphalogic_api.objects import ParameterLong
from alphalogic_api import init
from alphalogic_api.decorators import command


class MyRoot(Root):
    param_int = ParameterLong(default=2, visible=Visible.runtime, access=Access.read_only)
    simple_event = MajorEvent()

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

    @command(result_type=bool)
    def cmd_alarm(self):
        # do smth
        return True

class Controller(Object):

    counter = ParameterLong(default=0)

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

    # python loop
if __name__ == '__main__':
    host, port = init()
    root = MyRoot(host, port)
    root.join()

…

API Documentation¶

Objects¶

Root¶

User’s root object must be inherits from class Root:

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

class alphalogic_api.objects.Root¶

Root inherits from Object. The main object that connects to adapter.

Parameters:	host – hostname of the adapter with gRPC interface turned on port – port of the adapter

join()¶: The infinity communication loop

Object¶

Nodes inherits from class Object, except root node:

...
from alphalogic_api.objects import Object
...
class Controller(Object):
    ...

class alphalogic_api.objects.Object(type_device, id_device)¶

Node with parameters, commands, events and run functions. Parameters, commands, events can’t be with same name.

children()¶

Get list of children nodes

Return type:	list of types of children nodes

command(name)¶

Get command by name

Parameters:	name – name of command
Return type:	type is `Command`

commands()¶

Return commands for current node.

Return type:	list of `Command` #TODO

event(name)¶

Get event by name

Parameters:	name – name of event
Return type:	type is `Event`

events()¶

Return events for current node.

Return type:	list of `Event` #TODO

handle_before_remove_device()¶: Handler before remove device

handle_get_available_children()¶: Handler get available children

parameter(name)¶

Get parameter by name

Parameters:	name – name of parameter
Return type:	type is `Parameter`

parameters()¶

Return parameters for current node.

Return type:	list of `Parameter` #TODO

parent()¶

Get parent of node

Return type:	type of node

root()¶

Get root of node

Return type:	type of root node

Parameter¶

It will be possible to create types of parameter:

ParameterBool, ParameterLong, ParameterDouble, ParameterDatetime, ParameterString

Example of using:

hostname = ParameterString(visible=Visible.setup, access=Access.read_write, default='1', choices=('1', '2'))

Arguments of parameter are optional.

Argument	Default value	Possible values
default	ParameterLong - 0 ParameterBool - False ParameterDouble -0.0 ParameterDatetime - 0 ParameterString - “”	Any values of types are allowed ( for ParameterDouble is real number)
visible	Visible.runtime	Visible.runtime Visible.setup Visible.hidden Visible.common
access	Access.read_write	Access.read_write Access.read_only
choices	missing	The two possibilities are allowed. 1) list of values: (val1, val2, …) 2) list of tuple values with description ((val1, “desc1”), (val2, “desc2”))

Description of parameter’s arguments in constructor:
1) default is value of parameter by default
2) visible is method of display parameter in admin panel
3) access is method of access for user
4) choices is predefined values of parameter

In order to use predefined values for parameter need to use two field default and choices.

param_tmp = ParameterString(default='ster 31', choices=('ster 31', 'ster 25', 'ster 23'))

Case with value with description:

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

Class Parameter is defined in class scope:

class alphalogic_api.objects.Parameter(*args, **kwargs)¶: Parameter inherits from AbstractParameter.

Event¶

It will be possible to create types of event:

TrivialEvent, MinorEvent, MajorEvent, CriticalEvent, BlockerEvent

Names and values of arguments are passed by using tuple.

alarm = MajorEvent(('where', unicode), ('when', datetime.datetime), ('why', long))

First value of tuple is name of event’s argument , second is type of event’s argument.

List of possible type of arguments to create:

unicode, datetime.datetime, long, float, bool

Example of event emit:

alarm.emit(where=where, when=when, why=why)

If event without arguments:

alarm.emit()

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

Event inherits from AbstractEvent.

Parameters:	priority – trivial, minor, major, critical, blocker args – tuple of tuples (argument name, argument type)

Decorators¶

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 – Result type

run¶

class alphalogic_api.decorators.run¶

This function executes periodically. It also creates an integer Parameter which means period value in seconds.

Example:

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

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

Handlers¶

Three handlers may be installed by users:

1) Handle for request available children of node:

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

This function are should be define for all node who may to create children nodes.

2) A handler that fires after parameter is changed:

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)

If param_double is changed, then function handle_after_set_double will be called.

3) A handler that fires before node will be deleted:

def handle_before_remove_device(self):
    do something

Exceptions¶

class alphalogic_api.exceptions.IncorrectRPCRequest(msg)¶: Unsupported request by protocol. Check alphalogic_api code

class alphalogic_api.exceptions.RequestError(msg)¶: gRPC call exception

class alphalogic_api.exceptions.ComponentNotFound(msg)¶: If component not found in the Object

class alphalogic_api.exceptions.Exit¶

Abstract Classes¶

Abstract parameter¶

class alphalogic_api.objects.parameter.AbstractParameter¶

AbstractParameter implements ParameterService service(see rpc.proto)

clear()¶: Remove predefined values list

desc()¶

Return description of parameter

Return type:	unicode

display_name()¶

Return display name of parameter

Return type:	unicode

enums()¶

Get predefined values from parameter

Return type:	list of values (long, float, datetime, bool and unicode)

get()¶

Get value of parameter

Return type:	The possible types of value: long, float, datetime, bool and unicode

has_enum(enum_name)¶

Function return True if parameter has predefined values

Return type:	bool

is_bool()¶

Function return True if type of parameter is bool

Return type:	bool

is_common()¶

Function return True if visible type of parameter is common

Return type:	bool

is_datetime()¶

Function return True if type of parameter is datetime

Return type:	bool

is_double()¶

Function return True if type of parameter is double

Return type:	bool

is_hidden()¶

Function return True if visible type of parameter is hidden

Return type:	bool

is_licensed()¶

Function return True if parameter is licensed

Return type:	bool

is_long()¶

Function return True if type of parameter is long

Return type:	bool

is_read_only()¶

Function return True if access type of event is read only

Return type:	bool

is_read_write()¶

Function return True if access type of event is read write

Return type:	bool

is_runtime()¶

Function return True if visible type of parameter is runtime

Return type:	bool

is_setup()¶

Function return True if visible type of parameter is setup

Return type:	bool

is_string()¶

Function return True if type of parameter is string

Return type:	bool

name()¶

Return name of parameter

Return type:	unicode

owner()¶

Function return id of parameter’s owner

Return type:	uint64

set(value)¶

Set value of parameter

Parameters:	value – The possible types of value: long, float, datetime, bool and unicode

set_common()¶: Set visible type of event to common

set_desc(desc)¶

Set description of parameter

Parameters:	desc – unicode

set_display_name(display_name)¶

Set display name of parameter

Parameters:	display_name – unicode

set_enum(value, enum_name)¶

Add value to enum

Parameters:	value – The possible types of value: long, float, datetime, bool and unicode enum_name – name of enum to add new value

set_enums(values)¶

Set predefined values of parameter

Parameters:	values – List of predefined values.

set_hidden()¶: Set visible type of event to hidden

set_licensed()¶: The function licenses the parameter

set_read_only()¶: Set access type of event to read only

set_read_write()¶: Set access type of event to read write

set_runtime()¶: Set visible type of event to runtime

set_setup()¶: Set visible type of event to setup

Abstract event¶

class alphalogic_api.objects.event.AbstractEvent¶

AbstractEvent implements EventService service(see rpc.proto)

argument(name_argument)¶

Function return argument of event

Parameters:	name_argument – name of argument
Return type:	tuple (name, value) name is name of argument value is value of argument

argument_list()¶

Function return argument list of event

Return type:	list of arguments names

clear()¶: Remove event arguments

desc()¶

Return description of event

Return type:	unicode

display_name()¶

Return display name of event

Return type:	unicode

emit(**kwargs)¶

Function emit event with the current UTC time.

In order to set timestamp other than the current UTC time, you should call set_time function with required timestamp before execute emit function.

Parameters:	kwargs – arguments

is_blocker()¶

Function return True if type of event is blocker

Return type:	bool

is_critical()¶

Function return True if type of event is critical

Return type:	bool

is_major()¶

Function return True if type of event is major

Return type:	bool

is_minor()¶

Function return True if type of event is minor

Return type:	bool

is_trivial()¶

Function return True if type of event is trivial

Return type:	bool

name()¶

Return name of event

Return type:	unicode

owner()¶

Function return id of event’s owner

Return type:	uint64

set_argument(name_arg, value)¶

Set argument in event

Parameters:	name_arg – name of argument value – value of argument

set_blocker()¶: Set type of event to blocker

set_critical()¶: Set type of event to critical

set_desc(desc)¶

Set description of event

Parameters:	desc – unicode

set_display_name(display_name)¶

Set display name of event

Parameters:	display_name – unicode

set_major()¶: Set type of event to major

set_minor()¶: Set type of event to minor

set_time(timestamp)¶

Set event time UTC

Parameters:	timestamp – int(time.time() * 1000) (мс)

set_trivial()¶: Set type of event to trivial

Abstract command¶

class alphalogic_api.objects.command.AbstractCommand¶

AbstractCommand implements CommandService service(see rpc.proto)

argument(name_argument)¶

Function return argument of command

Parameters:	name_argument – name of argument
Return type:	tuple (name, value) name is name of argument value is value of argument

argument_list()¶

Function return argument list of command

Return type:	list of arguments names

clear()¶: Remove command’s arguments

desc()¶

Return description of command

Return type:	unicode

display_name()¶

Return display name of command

Return type:	unicode

is_bool()¶

Function return True if result type of command is bool

Return type:	bool

is_datetime()¶

Function return True if result type of command is datetime

Return type:	bool

is_double()¶

Function return True if result type of command is double

Return type:	bool

is_long()¶

Function return True if result type of command is long

Return type:	bool

is_string()¶

Function return True if result type of command is string

Return type:	bool

name()¶

Return name of command

Return type:	unicode

owner()¶

Function return id of command’s owner

Return type:	uint64

set_argument(name_arg, value)¶

Set argument in command

Parameters:	name_arg – name of argument value – value of argument

set_desc(desc)¶

Set description of command

Parameters:	desc – unicode

set_display_name(display_name)¶

Set display name of command

Parameters:	display_name – unicode

set_exception(reason)¶

Set exception in command. Information about exception will be called for adapter’s side.

Parameters:	reason – state unicode string

set_result(value)¶

Set result in command

Parameters:	value – The possible types of value: long, float, datetime, bool and unicode

Command¶

class alphalogic_api.objects.command.Command(device, function)¶

Command class is used in command decorator.

Command inherits from AbstractCommand.

Parameters:	device – has `Object` type function – executed function

call_function()¶

This function is performed when user call command

Return type:	result type is defined in function of adapter code

License¶

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contact¶

mo@alphaopen.com

Alphalogic API¶

Compatibility¶

Installation¶

Overview¶

Example Usage¶

API Documentation¶

Objects¶

Root¶

Object¶

Parameter¶

Event¶

Decorators¶

Command¶

run¶

Handlers¶

Exceptions¶

Abstract Classes¶

Abstract parameter¶

Abstract event¶

Abstract command¶

Command¶

License¶

Contact¶

Indices and tables¶