Changes between Version 1 and Version 2 of Tutorial

Timestamp:

Aug 14, 2013, 8:15:29 PM (11 years ago)

Author:

Frédéric

Comment:

--

Tutorial

@@ -1 +1 @@
 [[PageOutline(2-5, Table of Contents, floated)]]
 
+'''Draft''' 
+
 = Tutorial =
+
+== Architecture ==
+
+== Vocabulary ==
+
+TODO
+
+== Functional Blocks ==
+
+This is the central feature of '''pKNyX''', allowing user to create virtual devices which mimics real KNX devices. The Device itself is implemented as a process.
+
+Here is a very simple example which implements a timer. This timer can monitor the state of a light, and switch it off automatically after a delay. The code is taken from the {{{examples/3_timer}}} directory of ''pKNyX''' sources.
+
+{{{
+#!python
+from pknyx.api import Logger
+from pknyx.api import FunctionalBlock, Stack, ETS
+from pknyx.api import Scheduler, Notifier
+
+NAME = "timer"
+IND_ADDR = "1.2.3"
+
+# ETS group address map
+GAD_MAP = {"1": dict(name="lights", desc="Lights"),
+           "1/1": dict(name="cmds", desc="Commands"),
+           "1/1/1": dict(name="light_test_cmd", desc="Light 'test' (cmd)"),
+           "1/2": dict(name="states", desc="States"),
+           "1/2/1": dict(name="light_test_state", desc="Ligh 'test' (state)"),
+           "1/3": dict(name="delay", desc="Delays"),
+           "1/3/1": dict(name="light_test_delay", desc="Light 'test' (delay)"),
+          }
+
+
+logger = Logger("%s-%s" % (NAME, IND_ADDR))
+
+stack = Stack(individualAddress=IND_ADDR)
+ets = ETS(stack=stack, gadMap=GAD_MAP))
+
+schedule = Scheduler()
+notify = Notifier()
+
+
+class TimerFB(FunctionalBlock):
+    """ Timer functional block
+    """
+
+    # Datapoints definition
+    DP_01 = dict(name="cmd", access="output", dptId="1.001", default="Off")
+    DP_02 = dict(name="state", access="input", dptId="1.001", default="Off")
+    DP_03 = dict(name="delay", access="input", dptId="7.005", default=10)
+
+    GO_01 = dict(dp="cmd", flags="CWT", priority="low")
+    GO_02 = dict(dp="state", flags="CWUI", priority="low")
+    GO_03 = dict(dp="delay", flags="CWU", priority="low")
+
+    DESC = "Timer"
+
+    def _init(self):
+        """ Additionnal init of the timer
+        """
+        self._timer = 0
+
+    @schedule.every(seconds=1)
+    def updateTimer(self):
+        """ Method called every second.
+        """
+        #logger.trace("TimerFB.updateTimer()")
+
+        if self._timer:
+            self._timer -= 1
+            if not self._timer:
+                logger.info("%s: timer expired; switch off" % self._name)
+                self.dp["cmd"].value = "Off"
+
+    @notify.datapoint(dp="state", condition="change")
+    def stateChanged(self, event):
+        """ Method called when the 'state' datapoint changes
+        """
+        logger.debug("TimerFB.stateChanged(): event=%s" % repr(event))
+
+        if event['newValue'] == "On":
+            delay = self.dp["delay"].value
+            Logger().info("%s: start timer for %ds" % (self._name, delay))
+            self._timer = delay
+        elif event['newValue'] == "Off":
+            if self._timer:
+                Logger().info("%s: switched off detected; cancel timer" % self._name)
+                self._timer = 0
+
+    @notify.datapoint(dp="delay", condition="change")
+    def delayChanged(self, event):
+        """ Method called when the 'delay' datapoint changes
+        """
+        logger.debug("TimerFB.delayChanged(): event=%s" % repr(event))
+
+        # If the timer is running, we reset it to the new delay
+        if self._timer:
+            delay = self.dp["delay"].value
+            Logger().info("%s: delay changed; restart timer" % self._name)
+            self._timer = delay
+
+
+def main():
+
+    # Register functional block
+    ets.register(TimerFB, name="timer", desc="")
+
+    # Weave datapoints
+    ets.weave(fb="timer", dp="cmd", gad="1/1/1")
+    ets.weave(fb="timer", dp="state", gad="1/2/1")
+    ets.weave(fb="timer", dp="delay", gad="1/3/1")
+
+    print
+    ets.printGroat("gad")
+    print
+    ets.printGroat("go")
+    print
+    schedule.printJobs()
+    print
+
+    # Run the stack main loop (blocking call)
+    stack.mainLoop()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except:
+        logger.exception("3_main")
+}}}
+
+That's it! As you can see, concepts used here are simple... This Functional Block can now be used from any other real device of your installation, through Groups Addresses {{{1/1/1}}}, {{{1/3/1}}} and {{{1/3/1}}}. All you have to do, is to weave (link, bind...) the Group Objects of your real devices to these Groups Addresses, using the real '''ETS''' application. Sure, you can change the GAD to match your installation.
+
+Ok, now, lets start this device (invoke the python interpreter as for any other python script):
+
+{{{
+
+}}}
+
+
+Lets have a closer look to this example. First, we import some python objects:
+
+{{{
+#!python
+from pknyx.api import Logger
+from pknyx.api import FunctionalBlock, Stack, ETS
+from pknyx.api import Scheduler, Notifier
+}}}
+
+These objects are all classes.
+
+We then instanciante some high level objects and helpers:
+
+{{{
+#!python
+logger = Logger("%s-%s" % (NAME, IND_ADDR))
+
+stack = Stack(individualAddress=IND_ADDR)
+ets = ETS(stack=stack, gadMap=GAD_MAP))
+
+schedule = Scheduler()
+notify = Notifier()
+}}}
+
+The {{{Logger}}} object is a global logger service, which allow you to output all informations you want, at different levels. '''pKNyX''' make a big usage of that logger.
+
+The {{{Stack}}} object is used to communicate over the bus (real bus, of course, but also virtual bus). We can give it an Individual Address, to mimic real devices behaviour. This address will be used as Source Address when communicating over the bus. The address {{{0/0/0}}} is used by default.
+
+'''Important: to avoid internal loops, a device drops all telegrams sent by itself. So, if you want 2 virtal devices to communicate, you must ensure that they don't use the same source address.'''
+
+The {{{ETS}}} object is a tool which works more or less like the real ETS application (see below).
+
+The {{{Scheduler}}} is a helper implementating a powerfull scheduler (see below).
+The {{{Notifier}}} works the same way the {{{Scheduler}}} does, but does not provide the same features (see below).
+
+The main part is to create our custom Functional Block; this is done by subclassing the '''!FunctionBlock''' base class, and adding a few attributes/methods:
+
+{{{
+#!python
+class TimerFB(FunctionalBlock):
+    """ Timer functional block
+    """
+
+    # Datapoints definition
+    DP_01 = dict(name="cmd", access="output", dptId="1.001", default="Off")
+    DP_02 = dict(name="state", access="input", dptId="1.001", default="Off")
+    DP_03 = dict(name="delay", access="input", dptId="7.005", default=10)
+
+    GO_01 = dict(dp="cmd", flags="CWT", priority="low")
+    GO_02 = dict(dp="state", flags="CWUI", priority="low")
+    GO_03 = dict(dp="delay", flags="CWU", priority="low")
+
+    DESC = "Timer"
+
+    def _init(self):
+        """ Additionnal init of the timer
+        """
+        self._timer = 0
+}}}
+
+The {{{DP_xx}}} class attributes are the Datapoints of our Functional Block. The {{{GO_xx}}} class attributes are the Group Objects mapping the Datapoints to the bus through multicast service (Group Address). They are both defined as python dictionnary; they will be automatically instanciated for us by the framework. The named used here do not matter, as long as they start with {{{DP_}}} for Datapoints, and {{{GO_}}} for Group Objects.
+
+There are a few parameters in the dicts; some are obvious, some will need more explanations. But this is out of the scope of this tutorial.
+
+The {{{_init()}}} method is called when the functional block is instanciated; it can be used to init some needed global vars, or make initial tasks. Here, we just create the {{{_timer}}} var, and set it to 0.
+
+Ok, it's time to dig in the active part of our functional block. Let's start with the {{{stateChanged()}}} method:
+
+{{{
+#!python
+    @notify.datapoint(dp="state", condition="change")
+    def stateChanged(self, event):
+        """ Method called when the 'state' datapoint changes
+        """
+        logger.debug("TimerFB.stateChanged(): event=%s" % repr(event))
+
+        if event['newValue'] == "On":
+            delay = self.dp["delay"].value
+            Logger().info("%s: start timer for %ds" % (self._name, delay))
+            self._timer = delay
+        elif event['newValue'] == "Off":
+            if self._timer:
+                Logger().info("%s: switched off detected; cancel timer" % self._name)
+                self._timer = 0
+}}}
+
+This method as a '''decorator'''. If you don't know what is a decorator, have a look at this [excellent documentation.
+
+
+Note how this method is periodically called, using the {{{schedule.every()}}} method as python decorator. This decorator will automatically register our method and call it every 5 minutes.
+
+In this method, we get the temperature and humidity values (not explained here), and give these values to the respective Datapoints.
+
+Then, we register our new Funtional Block (this will automatically instanciate it - and do other things):
+
+{{{
+#!python
+ets.register(WeatherTemperatureBlock, name="weather_temperature", desc="A simple weather block example")
+}}}
+
+and use the {{{ETS}}} object to weave (bind, link...) our Datapoints (their matching Group Objects, in fact) to Group Addresses:
+
+{{{
+#!python
+ets.weave(fb="weatherTempBlock", dp="temperature", gad="1/1/1")
+ets.weave(fb="weatherTempBlock", dp="humidity", gad="1/1/2")
+}}}
+
+And finally, we launch the framework main loop:
+
+{{{
+#!python
+stack.mainLoop()
+}}}
+
+(this call is blocking).
+
+We now have a process (Device) running, listening to the bus. The Datapoints, through their respective Group Objects, will react to requests on the Group Addresses they are weaved to ("1/1/1" and "1/1/2"). According to the flags, they will transmit their internal value on Read requests or if their value internally change (updated). Yes, you don't have to manage this: '''pKNyX''' does it for you! This is the all point of a framework, isn't it?
+
+That's it for now. This is only a draft version; final implementation may change, according to feedback/suggestions I will get. But the core is all there. Again, the goal of the framework is to provide very high level tools to build complete and powerfull applications and KNX extensions.