[[PageOutline(2-5, Table of Contents, floated)]]

= Proposal =

This page is more or less a sandbox where I put my ideas. Feel free to comment.

== Main line ==

'''pKNyX''' is not a ready-to-use application: it is a '''framework'''. This means that it is up-to-you to write the application which fits your needs.

For that, you will need to know '''Python''', a powerfull , high level, object oriented, scripting language. Don't be afraid: Python is really easy to learn. It is now very popular, and used in many free and commercial applications to extend their capabilities. It is now even teached at school, to young people (~15 years old)! There are hundreds documentations, tutorials and examples on the web, and a huge community. Learning Python is really not a waste of time, and will help you to do many other tasks than simply building your KNX application!

'''pKNyX''' will provide you powerfull tools so you will only focus on '''your''' problem, and not on language subtilities, like it can be the case with other languages, like C, C++...

Ok, let me show you what I have in mind.

== Vocabulary ==

First, some definitions of terms and concepts I will use in '''pKNyX'''. They are the summary of my undersanding of the KNX specifications.

Unlike other standards, KNX is build arround the concept of ''Distributed Applications''. An application is split up into several '''Functional Blocks''', which can themselves be implemented in different '''Devices''' in the KNX network.

A Functional Block communicates over the bus through its '''Datapoints'''. A Datapoint can be an '''input''', an '''output''' or a '''parameter'''. For the real communication, a Datapoint can be implemented as '''Group Object''', '''Interface Object Property''', '''Polling Value''' or '''Memory Mapping'''. The most usefull is of course the Group Object.

To be able to communicate, Datapoints must have some well defined types, named '''Datapoint Types'''. These standardized Datapoint Types ensure the compatibility of the different devices made from many manufacturers. This another key point of the KNX bus.

'''pKNyX''' tries to follow as much as possible the KNX specifications in its implementation. This may not leads to the best architecture in term of efficiency, but I think it is the best way to have something easy to understand, maintain and improve. This can also  serve as a summary of all informations I can grab arround these specs.
== Functional Blocks ==

This will be the central feature of '''pKNyX''', allowing user to create virtual devices which mimics real KNX devices. The Device itself will be implemented as the process level.

Here is a very simple example of what I have in mind: creating a virtual minimalistic weather station, which uses informations from a non-KNX real weather-station, or from a web site. This station only implements temperature/humidity.

{{{
#!python
from pknyx.api import FunctionalBlock, Stack, ETS, Scheduler


stack = Stack(individualAddress="1.2.3")
ets = ETS(stack)
schedule = Scheduler()


class WeatherTemperatureBlock(FunctionalBlock):

    DP_01 = dict(name="temperature", access="output", dptId="9.001", default=19.)
    DP_02 = dict(name="humidity", access="output", dptId="9.007", default=50.)

    GO_01 = dict(dp="temperature", flags="CRT", priority="low")
    GO_02 = dict(dp="humidity", flags="CRT", priority="low")

    @schedule.every(minute=5)
    def updateTemperatureHumidity(self, event):
        # temperature = xxx
        # humidity = xxx
        self.dp["temperature"] = temperature
        self.dp["humidity"] = humidity


weatherTempBlock = WeatherTemperatureBlock(name="weather_tempertature", desc="A simple weather block example")

ets.register(weatherTempBlock)

ets.weave(fb=weatherTempBlock, dp="temperature", gad="1/1/1")
ets.weave(fb=weatherTempBlock, dp="humidity", gad="1/1/2")

stack.serve()
}}}

That's it! As you can see, concepts used here are simple... This Functional Block can be then used from any other real device of your installation, through Groups Addresses {{{1/1/1}}} and {{{1/1/2}}}. 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.

Lets have a closer look to this example. First, we import some python objects:

{{{
#!python
from pknyx.api import FunctionalBlock, Stack, ETS,  Scheduler
}}}

These objects are classes.

We then instanciante some high level objects and helpers:

{{{
#!python
stack = Stack(individualAddress="1.2.3")
ets = ETS(stack)
schedule = Scheduler()
}}}

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 {{{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 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 WeatherTemperatureBlock(FunctionalBlock):

    DP_01 = dict(name="temperature", access="output", dptId="9.001", default=19.)
    DP_02 = dict(name="humidity", access="output", dptId="9.007", default=50.)

    GO_01 = dict(dp="temperature", flags="CRT", priority="low")
    GO_02 = dict(dp="humidity", flags="CRT", priority="low")
}}}

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

In our class, we also defined a method which role is to update the temperature and humidity Datapoints values:

{{{
#!python
    @schedule.every(minute=5)
    def updateTemperatureHumidity(self, event):
        # temperature = xxx
        # humidity = xxx
        self.dp["temperature"].value = temperature
        self.dp["humidity"].value = humidity
}}}

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 the value to the respective Datapoints.

Then, we instanciate our new Funtional Block:

{{{
#!python
weatherTempBlock = WeatherTemperatureBlock(name="weather_tempertature", desc="A simple weather block example")
}}}

register it to {{{ETS}}} object:

{{{
#!python
ets.register(weatherTempBlock
}}}

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.serve()
}}}

(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.
== Simple rule ==

My first idea was to provide a special API to create rules, but in fact, they can be implemented as Functional Block. This way, we use the same paradigm, wich is always better ;o)

{{{
#!python
from pknyx.api import FunctionalBlock, Stack, ETS, Scheduler


stack = Stack(individualAddress="1.2.3")
ets = ETS(stack)
schedule = Scheduler()


class HeatingManagerBlock(FunctionalBlock):

    DP_01 = dict(name="temperature", access="input", dptId="9.001", default=19.)
    DP_02 = dict(name="setup", access="input", dptId="9.001", default=19.)
    DP_03 = dict(name="heater", access="output", dptId="1.001", default="Off")

    GO_01 = dict(dp="temperature", flags="CWU", priority="low")
    GO_02 = dict(dp="setup", flags="CWU", priority="low")
    GO_03 = dict(dp="heater", flags="CRT", priority="low")

    @schedule.every(minute=5)
    def manageHeater(self):

        # Read inputs
        temperature = self.dp["bathroom"].value
        setup = self.dp["setup"].value

        # Manage heater
        if temperature < setup - 0.25:
            heater = "On"
        elif temperature > setup + 0.25:
            heater = "Off"

        # Set outputs
        self.dp["bathroom_heater"].value = heater


heatingManagerBlock = HeatingManagerBlock(name="heating_manager", desc="A simple heating manager block example")

ets.register(heatingManagerBlock)

ets.weave(fb=heatingManagerBlock, dp="temperature", gad="1/1/1")
ets.weave(fb=heatingManagerBlock, dp="setup", gad="1/1/2")
ets.weave(fb=heatingManagerBlock, dp="heater", gad="1/1/3")

stack.serve()
}}}

All you have to do is to use the Group Addresses you use in your real installation, through ETS application. The first one will update the temperature the Functional Block needs; the second one is used to give the setpoint, and the last one is used to switch on/off a real heater, through a KNX actuator.

Note that it is possible to instanciate several heating managers, and weave them to different heaters.

A more complex heating manager could compute a PID and output the power to use to heat.
== '''linknx''' compatibility mode ==

As I still want to use knxweb, I also plan to develop a special device-like object to mimic '''linknx''' behaviour. All it has to do is to provide the basic xml services used by clients, to display bus status and send orders. Other features, like advanced configuration, rules and so, will be omitted.

Again, we can use the same paradigm as for virtual devices and rules. The framework will provide another custom class for that purpose, but it will be used the same way. It will just add specific features, and the internal structure to act as a '''linknx'''-like server.

== Specific server mode ==

The purpose of this will be to provide the model part of an automatic web page generation mechanism. I don't know yet how it will exactly work, but the idea is to provide a simple list of usefull informations/settings which can be used from smartphones (simples buttons and displays).
== Unsorted ideas ==

 * each rule/device can be a process, rather than a thread. User choice.
 * create managers to get status of all run applications