# Description of API for python-eledio library

This description allow to you easly write your own python script.

This script you can use for control of your Eledio devices. This sript you can upload to your Eledio Gateway and control your gateways and your Eledio Extendres which you want control from gateway.

This library is preinstalled in your Eledio Gateway. You can start programming, after unpacking.

## Necessary parts

Each major drive script in python for your application must be made up with some necessary parts.

- device description in json file

- import of library components

- load of json file

### Device description in json file

- this file is for hardware abstraction layer to linux
- you are able to used your own names of identifiers, eg. you can rename Temperature to OutsideTemperature
- every name of identifiers must consist only with English alphabet characters, without spaces and other punctuation
- if you need some reaclculation of readout values, you can use prepared values a and b, with are parts of equation y=a*x+b, where x is readout value from device, y is value which you obtain in python script, eg. if you need temeperature in degree of fahrenheit, you can place a=1.8 and b=32 (which corresponds of equation `T[°F] = T[°C]*1.8 + 32`)

#### Example of json file, can be named as config.json

    {
      "devices": {
        "unit-40": {
          "bus": "i2c",
          "address": 40,
          "datacrc": 9718,
          "compilermagic": 4006394777
        }
      },
      "identifiers": {
        "gatewayHWEvent": {
          "unit": "unit-40",
          "partition": "sdp",
          "offset": 0,
          "entrysize": 2,
          "depth": 0,
          "type": 1,
          "prescaler": 0,
          "a": 1,
          "b": 0,
          "datatype": "u16",
          "srq": 0
        },
        "gatewayHWState": {
          "unit": "unit-40",
          "partition": "sdp",
          "offset": 2,
          "entrysize": 2,
          "depth": 0,
          "type": 1,
          "prescaler": 0,
          "a": 1,
          "b": 0,
          "datatype": "u16"
        },
        "RE1Voltage": {
          "unit": "unit-40",
          "partition": "sdp",
          "offset": 4,
          "entrysize": 2,
          "depth": 0,
          "type": 1,
          "prescaler": 0,
          "a": 0.01,
          "b": 0,
          "datatype": "s16"
        },
        "Temperature": {
          "unit": "unit-40",
          "partition": "sdp",
          "offset": 6,
          "entrysize": 2,
          "depth": 0,
          "type": 1,
          "prescaler": 0,
          "a": 0.01,
          "b": 0,
          "datatype": "s16"
        },
        "gatewayHWAction": {
          "unit": "unit-40",
          "partition": "adp",
          "offset": 0,
          "entrysize": 2
        },
        "RE1": {
          "unit": "unit-40",
          "partition": "adp",
          "offset": 2,
          "entrysize": 1
        },
        "RE3": {
          "unit": "unit-40",
          "partition": "adp",
          "offset": 3,
          "entrysize": 1
        }
      }
    }

### Import of library components

- consist with few of import statements, which are necessary for correct function

    import json # necessary for description json file; required

    from eledio import Eledio   # basic functionality; required
    from eledio.component.mpu.i2c import SMBus  # communication interface with linux; required
    from eledio.device.pcu import PcuFactory    # access to variables and components of base board, e.g: relay outputs, digital inputs, ...; required
    from eledio.device.mpu import MpuFactory # access to variables and components of linux board, e.g.: wifi signal rssi, status LED color, ...
    from eledio.device.srq import Srq   # interrupt system for quick access to variables which need intermediate handle, e.g.: RF433 receiver

### Load of json file

- this part is required before fist try of attempt to variables with names form config json part

#### Basic example of device registration

    eledio = Eledio()
    eledio.register_device_factory("i2c", PcuFactory(SMBus(0)))

    # repeat for every configuration file
    with open('config.json') as f:
        eledio.append_config(json.load(f))

## Readout values from the peripherals - sensors, to linux

Everytime, you want to read all of variables, e.g.: temperatures, digital input states, sensors values, ... you must to call `eledio.load_inputs()`

After this calling, you can access to variables by their symbloc names in dict access. For example:

    eledio.load_inputs()

    temperature = eledio["Temperature"] # this statement put value of temperature after processing of linear equation (a and b coeficients) to the variable temperature

    voltage = eledio["RE1Voltage"] # this statement put value of RMS voltage on relay 1 to variable voltage

## Put new values to the peripherals - actuators, connected to the hardware

For relay, digital outputs you are able to set states True/False. Used logic of every component is written in component description.

    eledio["RE1"] = True # switch on relay 1
    eledio["RE3"] = False # switch off relay 3

    eledio.store_outputs()

After setting values for all of dict `eledio` parts, which you want to set, you need to call command `eledio.store_outputs()`, which send that values to real hardware.

« Previous Next »