Add original source codes

docs/api_description.md

@@ -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.

docs/application_example.md

@@ -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)
+```

docs/contact.md

@@ -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**

docs/index.md

@@ -0,0 +1,9 @@
+# Python Eledio library documentation
+
+![Eledio logo](img/Eledio_logo.png)
+
+Welcome to Eledio library documentation pages
+
+## Note
+
+__This library and documantation can be aplied only for devices from Eledio ecosystem__

mkdocs.yml

@@ -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