mirror of
https://github.com/Eledio/python-eledio.github.io.git
synced 2025-10-31 00:12:32 +01:00
Add original source codes
This commit is contained in:
Richard Kubíček
158
docs/api_description.md
Normal file
158
docs/api_description.md
Normal file
@@ -0,0 +1,158 @@
|
||||
---
|
||||
summary: Documentation site of Python Eledio library
|
||||
authors:
|
||||
- Richard Kubicek
|
||||
date: 2019-09-27
|
||||
---
|
||||
# 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__](https://www.eledio.com/en/hardware/) and control your gateways and your [__Eledio Extendres__](https://www.eledio.com/en/hardware/) which you want control from gateway.
|
||||
|
||||
This library is preinstalled in your [Eledio Gateway](https://www.eledio.com/en/hardware/). 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](#device-description-in-json-file)
|
||||
|
||||
* [import of library components](#import-of-library-components)
|
||||
|
||||
* [load of _json_ file](#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.
|
||||
253
docs/application_example.md
Normal file
253
docs/application_example.md
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
summary: Application example of Python Eledio library
|
||||
authors:
|
||||
- Richard Kubicek
|
||||
date: 2019-09-06
|
||||
---
|
||||
# Example of usages
|
||||
There you can find some examples, how to use python-eledio library in your Eledio devices.
|
||||
|
||||
## State LED, buzzer and watchdog control
|
||||
### Configuration _json_ file
|
||||
File name: _mpu-config.json_
|
||||
```
|
||||
{
|
||||
"devices": {
|
||||
"mpu-dev": {
|
||||
"bus": "mpu"
|
||||
}
|
||||
},
|
||||
"identifiers": {
|
||||
"mpuWifiRssi": {
|
||||
"unit": "mpu-dev",
|
||||
"parameter": "wifi-rssi"
|
||||
},
|
||||
"mpuInternalTemperature": {
|
||||
"unit": "mpu-dev",
|
||||
"parameter": "temperature"
|
||||
},
|
||||
"mpuCpuPercent": {
|
||||
"unit": "mpu-dev",
|
||||
"parameter": "cpu-percent"
|
||||
},
|
||||
"mpuLed": {
|
||||
"unit": "mpu-dev",
|
||||
"parameter": "led"
|
||||
},
|
||||
"mpuBeeper": {
|
||||
"unit": "mpu-dev",
|
||||
"parameter": "beeper"
|
||||
},
|
||||
"mpuWatchdog": {
|
||||
"unit": "mpu-dev",
|
||||
"parameter": "watchdog"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
### Usage
|
||||
```
|
||||
import json
|
||||
|
||||
from eledio import Eledio
|
||||
from eledio.component.mpu.i2c import SMBus
|
||||
from eledio.device.mpu import MpuFactory
|
||||
|
||||
if __name__ == "__main__":
|
||||
eledio = Eledio()
|
||||
eledio.register_device_factory("mpu", MpuFactory())
|
||||
|
||||
with open('mpu-config.json') as f:
|
||||
eledio.append_config(json.load(f))
|
||||
|
||||
eledio["mpuLed"] = (0x40, 0x00, 0x00) # set color of state LED in (R, G, B) format
|
||||
eledio["mpuBeeper"] = (1500, 10) # after calling store_outputs() switch on beeper on frequency 1500 Hz for 1s (first parameter is frequency in Hz, second parameter is duration in hundred ms)
|
||||
|
||||
'''
|
||||
Warning, next statement is dangerous, it couse restart of linux machine (watchdog).
|
||||
This function is good to use when you have your development complete, and you know, that you communicate with components and devices lower then every x second.
|
||||
'''
|
||||
eledio["mpuWatchdog"] = 120 # after calling store_outputs() this statement couse reset of linux every 120 seconds. If there is any communication with devicese, timeout is restarted.
|
||||
|
||||
eledio.store_outputs()
|
||||
```
|
||||
## WiFi RSSI, linux CPU utilization
|
||||
Use [same _json_](#configuration-json-file) file as in previous example.
|
||||
### Usage
|
||||
```
|
||||
import json
|
||||
|
||||
from eledio import Eledio
|
||||
from eledio.component.mpu.i2c import SMBus
|
||||
from eledio.device.mpu import MpuFactory
|
||||
|
||||
if __name__ == "__main__":
|
||||
eledio = Eledio()
|
||||
eledio.register_device_factory("mpu", MpuFactory())
|
||||
|
||||
with open('mpu-config.json') as f:
|
||||
eledio.append_config(json.load(f))
|
||||
|
||||
eledio.load_inputs()
|
||||
|
||||
rssi = eledio["mpuWifiRssi"] # place to variable rssi, WiFi signal RSSI
|
||||
utilization = eledio["mpuCpuPercent"] # place to variable utilitation, linux CPU utilization
|
||||
```
|
||||
## SRQ/IRQ handler
|
||||
If you want to used quick access to variables like received code from RF433 control, you can use SRQ handler.
|
||||
|
||||
Inside SRQ handler, in this example function ```handle_srq```, you received dictionary of eledio identifiers and their new value after SRQ.
|
||||
### Configuration _json_ file
|
||||
File name: _map.json_
|
||||
```
|
||||
{
|
||||
"devices": {
|
||||
"unit-40": {
|
||||
"bus": "i2c",
|
||||
"address": 40,
|
||||
"datacrc": 43200,
|
||||
"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"
|
||||
},
|
||||
"rf433": {
|
||||
"unit": "unit-40",
|
||||
"partition": "sdp",
|
||||
"offset": 4,
|
||||
"entrysize": 4,
|
||||
"depth": 0,
|
||||
"type": 1,
|
||||
"prescaler": 0,
|
||||
"a": 1,
|
||||
"b": 0,
|
||||
"datatype": "u32",
|
||||
"srq": 1
|
||||
},
|
||||
"gatewayHWAction": {
|
||||
"unit": "unit-40",
|
||||
"partition": "adp",
|
||||
"offset": 0,
|
||||
"entrysize": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
### Usage
|
||||
```
|
||||
import json
|
||||
|
||||
from eledio import Eledio
|
||||
from eledio.component.mpu.i2c import SMBus
|
||||
from eledio.device.mpu import MpuFactory
|
||||
|
||||
def handle_srq(identifiers):
|
||||
"""
|
||||
User handling of SRQ (called in context of eledio.wait_events)
|
||||
:param identifiers: dictionary of eledio identifiers and their new value after SRQ
|
||||
:return:
|
||||
"""
|
||||
print("Service requests!", identifiers)
|
||||
|
||||
if __name__ == "__main__":
|
||||
eledio = Eledio()
|
||||
eledio.register_device_factory("i2c", PcuFactory(SMBus(0)))
|
||||
eledio.register_srq(Srq(), handle_srq())
|
||||
|
||||
# repeat for every configuration file
|
||||
with open('map.json') as f:
|
||||
eledio.append_config(json.load(f))
|
||||
|
||||
while True:
|
||||
# load state of inputs and outputs
|
||||
eledio.load_inputs()
|
||||
|
||||
# do something else or wait some time
|
||||
eledio.wait_events(1.0)
|
||||
```
|
||||
## Error handler
|
||||
In runtime and while you develop your solution, there could rise some errors. You can catch them by definition of _error handler_.
|
||||
### Usage
|
||||
In this example _error handler_ is represented by function ```handler_error```.
|
||||
```
|
||||
import json
|
||||
|
||||
from eledio import Eledio
|
||||
from eledio.component.mpu.i2c import SMBus
|
||||
from eledio.device.pcu import PcuFactory
|
||||
from eledio.device.mpu import MpuFactory
|
||||
from eledio.device.srq import Srq
|
||||
|
||||
|
||||
def handle_srq(identifiers):
|
||||
"""
|
||||
User handling of SRQ (called in context of eledio.wait_events)
|
||||
:param identifiers: dictionary of eledio identifiers and their new value after SRQ
|
||||
:return:
|
||||
"""
|
||||
print("Service requests!", identifiers)
|
||||
|
||||
|
||||
def handle_error(src, ex):
|
||||
"""
|
||||
Handle error inside eledio library
|
||||
:param src:
|
||||
:param ex:
|
||||
:return:
|
||||
"""
|
||||
print(src, ex)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
eledio = Eledio()
|
||||
eledio.register_device_factory("i2c", PcuFactory(SMBus(0)))
|
||||
eledio.register_device_factory("mpu", MpuFactory())
|
||||
eledio.register_srq(Srq(), handle_srq)
|
||||
eledio.error_handler = handle_error
|
||||
|
||||
# repeat for every configuration file
|
||||
with open('config.json') as f:
|
||||
eledio.append_config(json.load(f))
|
||||
|
||||
with open('mpu-config.json') as f:
|
||||
eledio.append_config(json.load(f))
|
||||
|
||||
while True:
|
||||
# load state of inputs and outputs
|
||||
eledio.load_inputs()
|
||||
|
||||
# manipulate with inputs and outputs by identifier
|
||||
# e.g.
|
||||
# print(eledio["test1"])
|
||||
# eledio["test2"] = True
|
||||
|
||||
# apply final value to hardware
|
||||
eledio.store_outputs()
|
||||
|
||||
# do something else or wait some time
|
||||
eledio.wait_events(1.0)
|
||||
```
|
||||
7
docs/contact.md
Normal file
7
docs/contact.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Contact
|
||||
|
||||
If you have any question please contact us on email: [eledio@eledio.com](mailto:%20eledio@eledio.com)
|
||||
|
||||
WWW: [eledio.com](https://eledio.com)
|
||||
|
||||
tel.: +420 **724 328 130**
|
||||
BIN
docs/img/Eledio_logo.png
Normal file
BIN
docs/img/Eledio_logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.2 KiB |
9
docs/index.md
Normal file
9
docs/index.md
Normal file
@@ -0,0 +1,9 @@
|
||||
# Python Eledio library documentation
|
||||
|
||||
|
||||
|
||||
Welcome to Eledio library documentation pages
|
||||
|
||||
## Note
|
||||
|
||||
__This library and documantation can be aplied only for devices from Eledio ecosystem__
|
||||
13
mkdocs.yml
Normal file
13
mkdocs.yml
Normal file
@@ -0,0 +1,13 @@
|
||||
site_name: Python Eledio library
|
||||
nav:
|
||||
- Home: index.md
|
||||
- API description: api_description.md
|
||||
- Application example: application_example.md
|
||||
- Contact: contact.md
|
||||
theme:
|
||||
name: readthedocs
|
||||
highlightjs: true
|
||||
hljs_languages:
|
||||
- python
|
||||
copyright: Eledio © 2019
|
||||
site_description: Documentation site of Python Eledio library
|
||||
Reference in New Issue
Block a user