Difference between revisions of "KONNEKTING Device Library"

From KONNEKTING Wiki
Jump to navigation Jump to search
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== Supported microcontrollers ==
+
== Hardware Requirements ==
  
−
* Atmel SAMD21G18J
+
* [http://www.atmel.com/products/microcontrollers/ARM/SAM-D.aspx#samd21 Atmel SAMD21G18J]
−
* Atmel ATMega 328P (*deprecated)
+
* [http://www.atmel.com/devices/ATMEGA328P.aspx Atmel ATMega 328P (*deprecated)]
−
* Atmel ATMega 32U4 (*deprecated)
+
* [http://www.atmel.com/devices/atmega32u4.aspx Atmel ATMega 32U4 (*deprecated)]
−
* Espressiv ESP8266
+
* [https://www.espressif.com/en/products/hardware/esp8266ex/overview Espressif ESP8266 (experimental)]
  
−
Other microcontrollers, especially from Atmel might work, but there could be issues that you have to solve yourself.  
+
(*)deprecated = will be sonner or later "dropped" and not actively supported/maintained
 +
 
 +
Other (Arduino compatible) controllers might work as well. But don't expect that they work flawlessly without adapting our library code. We try to keep the number of directly supported controllers short, so that the overall maintenance is easy. We don't want to add dozens of if-else-compiler-flags to support each and every available microcontroller. You can do this by yourself. But please accept that this will not be merged in the public code (maintenance ...)
 +
 
 +
You need at least two free pins on the microcontroller for
 +
 
 +
* Programming Button
 +
* Programming LED
  
−
(*)deprecated = will be sonner or later "dropped" and not actively supported/maintained
+
It is required, that the programming button is connected to a pin on the microcontroller which is capable of a real harwdare interrupt. Internally we use the attachInterrupt() Arduino function (https://www.arduino.cc/en/Reference/attachInterrupt). So make sure your button is connected to a pin that is supported by this function.
 +
 
 +
The pin on the microcontroller for the LED can be any digital output pin.
  
 
[[KONNEKTING_XML_Device_Description | KONNEKTING XML Device Description ".kdevice.xml"]]
 
[[KONNEKTING_XML_Device_Description | KONNEKTING XML Device Description ".kdevice.xml"]]
Line 14: Line 23:
 
-----
 
-----
  
−
== KONNEKTING Device Library
+
== KONNEKTING Device Library ==
  
 
The device library enables the Arduino to connect to the KNX bus.  
 
The device library enables the Arduino to connect to the KNX bus.  
  
−
=== Example Sketch Explained
+
=== Example Sketch Explained ===
  
 
<syntaxhighlight lang=c++ line>
 
<syntaxhighlight lang=c++ line>
Line 106: Line 115:
  
 
=== API ===
 
=== API ===
−
==== 1 / Define the communication objects ====
+
 
 +
Instead of explaining method by method without any context, we try to explain the code and the API with an step by step approach.
 +
 
 +
==== Define the communication objects ====
  
 
First of all, define the KNX communication objects of your bus device. For each object, define its datapoint type, and its flags. Theoritically, you can define up to 255 objects, even if in practical you are limited by the quantity of RAM (it would be worth measuring the max allowed number of objects depending on the memory available).
 
First of all, define the KNX communication objects of your bus device. For each object, define its datapoint type, and its flags. Theoritically, you can define up to 255 objects, even if in practical you are limited by the quantity of RAM (it would be worth measuring the max allowed number of objects depending on the memory available).
Line 113: Line 125:
  
 
'''Description:'''  list of the communication objects (group objects) that are attached to your KNX device. Define this variable in your Arduino sketch (but outside all function bodies).
 
'''Description:'''  list of the communication objects (group objects) that are attached to your KNX device. Define this variable in your Arduino sketch (but outside all function bodies).
−
'''Parameters:''' for each object in the list, you shall provide the group address (word, use G_ADDR() function), the datapoint type (check "_e_KnxDPT_ID_" enum in [KnxDPT.h](https://github.com/franckmarini/KnxDevice/blob/master/KnxDPT.h) file), and the flags (byte, check [KnxComObject.h](https://github.com/franckmarini/KnxDevice/blob/master/KnxComObject.h) for more details).  
+
 
 +
'''Parameters:''' for each object in the list, you shall provide the group address (word, use ''G_ADDR()'' function), the datapoint type (check "_e_KnxDPT_ID_" enum in [https://github.com/franckmarini/KnxDevice/blob/master/KnxDPT.h KnxDPT.h] file), and the flags (byte, check [https://github.com/franckmarini/KnxDevice/blob/master/KnxComObject.h KnxComObject.h] for more details).  
  
 
'''Example:'''
 
'''Example:'''
Line 123: Line 136:
 
KnxComObject{KNX_DPT_1_003 /* 1.003 B1 DPT_Enable*/ ,       0x30 /* C+R */ }
 
KnxComObject{KNX_DPT_1_003 /* 1.003 B1 DPT_Enable*/ ,       0x30 /* C+R */ }
 
</syntaxhighlight>
 
</syntaxhighlight>
−
___
 
−
**`const byte KnxDevice::_comObjectsNb = sizeof(_comObjectsList) / sizeof(KnxComObject);`**
 
−
* **Description:** Define the number of group objects in the list. Simply copy the above code as is in your Arduino sketch!
 
  
−
==== 2/ Init KNX device ====
 
−
___
 
−
**`void init(HardwareSerial& serial, int progButtonPin, int progLedPin, word manufacturerID, byte deviceID, byte revisionID);`**
 
−
* **Description:**  Start the KNX Device. Place this function call in the setup() function of your Arduino sketch
 
−
* **Parameters :** serial = serial port that is connected to the KNX TPUART Transceiver, progButtonPin = arduino pin which is connected to the prog button and **is capable of an real interrupt**, progLedPin = arduino pin which is connected to the programming LED, [manufacturerID = your manufacturer ID](konnekting_manufacturers.md), deviceID = ID identifying your device, revision = revision of your firmware (increment if new version is no longer backwards-compatible)
 
  
−
* **Example:**
+
----
−
```
+
 
 +
 
 +
<syntaxhighlight lang="c++" inline>const byte KnxDevice::_comObjectsNb = sizeof(_comObjectsList) / sizeof(KnxComObject);</syntaxhighlight>
 +
 
 +
'''Description:''' Define the number of group objects in the list. Simply copy the above code as is in your Arduino sketch!
 +
 
 +
==== Init KNX device ====
 +
 
 +
<syntaxhighlight lang="c++" inline>void init(HardwareSerial& serial, int progButtonPin, int progLedPin, word manufacturerID, byte deviceID, byte revisionID);</syntaxhighlight>
 +
 
 +
'''Description:'''  Start the KNX Device. Place this function call in the setup() function of your Arduino sketch
 +
 
 +
'''Parameters:''' serial = serial port that is connected to the KNX TPUART Transceiver, progButtonPin = arduino pin which is connected to the prog button and **is capable of an real interrupt**, progLedPin = arduino pin which is connected to the programming LED, [manufacturerID = your manufacturer ID](konnekting_manufacturers.md), deviceID = ID identifying your device, revision = revision of your firmware (increment if new version is no longer backwards-compatible)
 +
 
 +
'''Example:'''
 +
<syntaxhighlight lang="c++" line>
 
Konnekting.init(KNX_SERIAL,  
 
Konnekting.init(KNX_SERIAL,  
 
               PROG_BUTTON_PIN,  
 
               PROG_BUTTON_PIN,  
Line 141: Line 161:
 
               DEVICE_ID,  
 
               DEVICE_ID,  
 
               REVISION);
 
               REVISION);
−
```
+
</syntaxhighlight>
 +
 
 +
 
 +
----
 +
 
 +
 
 +
<syntaxhighlight lang="c++" inline>void task(void);</syntaxhighlight>
 +
 
 +
'''Description:'''  KNX device execution task. This function call shall be placed in the "loop()" Arduino function.
 +
 
 +
'''WARNING:''' this function shall be called periodically (400us max period) meaning usage of functions stopping the execution (like ''delay()'', visit http://playground.arduino.cc/Code/AvoidDelay for more info) is FORBIDDEN.
  
−
___
+
'''Example:'''
−
**`void task(void);`**
+
 
−
* **Description:**  KNX device execution task. This function call shall be placed in the "loop()" Arduino function. **WARNING : this function shall be called periodically (400us max period) meaning usage of functions stopping the execution (like delay(), visit http://playground.arduino.cc/Code/AvoidDelay for more info) is FORBIDDEN.**
+
<syntaxhighlight lang="c++" line>
−
* **Example:**
 
−
```
 
 
Knx.task();
 
Knx.task();
−
```
+
</syntaxhighlight>
 +
 
 +
 
 +
====  Interact with the communication objects ====
  
−
___
 
−
==== 3/ Interact with the communication objects ====
 
 
The API allows you to interact with objects that you have defined : you can read and modify their values, force their value to be updated with the value on the bus. You are also notified each time objects get their value changed following a bus access :
 
The API allows you to interact with objects that you have defined : you can read and modify their values, force their value to be updated with the value on the bus. You are also notified each time objects get their value changed following a bus access :
−
___
 
−
**`void knxEvents(byte objectIndex);`**
 
  
−
  _Notify object updates performed via the bus_
+
<syntaxhighlight lang="c++" inline>void knxEvents(byte objectIndex);</syntaxhighlight>
 +
 
 +
'''Description:'''  callback function that is called by the KnxDevice library every time a group object is updated by the bus. Define this function in your Arduino sketch.
 +
 
 +
'''Parameters :''' "''objectIndex''" is the index (in the list) of the object updated by the bus
 +
 
 +
'''Example:'''
  
−
* **Description:**  callback function that is called by the KnxDevice library every time a group object is updated by the bus. Define this function in your Arduino sketch.
+
<syntaxhighlight lang="c++" line>
−
* **Parameters :** "objectIndex" is the index (in the list) of the object updated by the bus
 
−
* **Example:**
 
−
```
 
 
// Callback function to treat object updates
 
// Callback function to treat object updates
 
void knxEvents(byte index) {
 
void knxEvents(byte index) {
Line 182: Line 212:
 
   }
 
   }
 
};
 
};
−
```
+
</syntaxhighlight>
 +
 
 +
 
 +
Quick method to get the value of a short object:
 +
 
 +
<syntaxhighlight lang="c++" inline>byte Knx.read(byte objectIndex);</syntaxhighlight>
 +
 
 +
'''Description:''' Get the current value of a short group object. This function is relevant for _short_ objects only, see table below. The returned value will be hazardous in case of use with _long_ objects.
 +
 
 +
'''Parameters:''' "objectIndex" is the index (in the list) of the object to be read.
 +
 
 +
'''Return:''' the current value of the object.
 +
 
 +
'''Example:'''
 +
 
 +
<syntaxhighlight lang="c++" line>Knx.read(0); // return index 0 object value</syntaxhighlight>
 +
 
 +
----
 +
 
 +
{| class="wikitable" style="text-align:center"
 +
!Supported KNX DPT formats
 +
!Remark
 +
|-
 +
|KNX_DPT_FORMAT_B1
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B2
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B1U3
 +
|bit fields to be computed by user application
 +
|-
 +
|KNX_DPT_FORMAT_A8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_U8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B5N3
 +
|bit fields to be computed by user application
 +
|}
 +
 
 +
----
  
−
___
 
−
**`byte Knx.read(byte objectIndex);`**
 
  
−
  _Quick method to get the value of a short object_
+
Read an usual format com object
  
−
* **Description:** Get the current value of a short group object. This function is relevant for _short_ objects only, see table below. The returned value will be hazardous in case of use with _long_ objects.
+
<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.read(byte objectIndex, <any standard C type>& returnedValue);</syntaxhighlight>
−
* **Parameters:** "objectIndex" is the index (in the list) of the object to be read.
 
−
* **Return:** the current value of the object.
 
−
* **Example:** ```Knx.read(0); // return index 0 object value```
 
  
−
| supported KNX DPT formats  |        Remark                                      |
+
'''Description:''' Get the current value of a group object. This function is relevant for objects with usual format, see table below.
−
|:---------------------------:|:----------------------------------------------------:|
 
−
| KNX_DPT_FORMAT_B1          |                                                      |
 
−
| KNX_DPT_FORMAT_B2          |                                                      |
 
−
| KNX_DPT_FORMAT_B1U3        | bit fields to be computed by user application        |
 
−
| KNX_DPT_FORMAT_A8          |                                                      |
 
−
| KNX_DPT_FORMAT_U8          |                                                      |
 
−
| KNX_DPT_FORMAT_V8          |                                                      |
 
−
| KNX_DPT_FORMAT_B5N3        | bit fields to be computed by user application        |
 
  
−
___
+
'''Parameters:''' "objectIndex" is the index (in the list) of the object to be read. "returnedValue" is the read com object value. "returnedValue" can be any standard C type (boolean, uchar, char, uint, int, ulong, long, float, double types).
−
**`e_KnxDeviceStatus Knx.read(byte objectIndex, <any standard C type>& returnedValue);`**
 
  
−
  _Read an usual format com object_
+
'''Return:''' KNX_DEVICE_OK (0) when everything went well, KNX_DEVICE_NOT_IMPLEMENTED (254) in case of F32 conversion, KNX_DEVICE_ERROR (255) in case of unsupported group object format.
  
−
* **Description:** Get the current value of a group object. This function is relevant for objects with usual format, see table below.
+
'''Examples:'''
−
* **Parameters:** "objectIndex" is the index (in the list) of the object to be read. "returnedValue" is the read com object value. "returnedValue" can be any standard C type (boolean, uchar, char, uint, int, ulong, long, float, double types).
+
 
−
* **Return:** KNX_DEVICE_OK (0) when everything went well, KNX_DEVICE_NOT_IMPLEMENTED (254) in case of F32 conversion, KNX_DEVICE_ERROR (255) in case of unsupported group object format.
+
<syntaxhighlight lang="c++" line>
−
* **Examples:**
 
−
```
 
 
byte i; Knx.read(0,i); // read index 0 object (short object)
 
byte i; Knx.read(0,i); // read index 0 object (short object)
 
unsigned int j; Knx.read(1,j); // read index 1 object (U16 format)
 
unsigned int j; Knx.read(1,j); // read index 1 object (U16 format)
Line 220: Line 279:
 
long m; Knx.read(4,m); // read index 4 object (V32 format)
 
long m; Knx.read(4,m); // read index 4 object (V32 format)
 
float n; Knx.read(5,n); // read index 5 object (F16/F32 format)
 
float n; Knx.read(5,n); // read index 5 object (F16/F32 format)
−
```
+
</syntaxhighlight>
 +
 
 +
{| class="wikitable" style="text-align:center"
 +
!Supported KNX DPT formats
 +
!Remark
 +
|-
 +
|KNX_DPT_FORMAT_B1
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B2
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B1U3
 +
|bit fields to be computed by user application
 +
|-
 +
|KNX_DPT_FORMAT_A8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_U8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B5N3
 +
|bit fields to be computed by user application
 +
|-
 +
|KNX_DPT_FORMAT_U16
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V16
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_F16
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_U32
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V32
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_F32
 +
|''!!not yet implemented!!''
 +
|}
 +
 
 +
 
 +
----
 +
 
 +
Read ANY format com object (advised to advanced users only)
 +
 
 +
<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.read(byte objectIndex, byte returnedValue[]);</syntaxhighlight>
  
−
| supported KNX DPT formats   |        Remark                                      |
+
'''Description:''' read the value of a group object. This function supports ALL the DPT formats, the returned value has a rough DPT format.
−
|:---------------------------:|:----------------------------------------------------:|
 
−
| KNX_DPT_FORMAT_B1          |                                                      |
 
−
| KNX_DPT_FORMAT_B2          |                                                      |
 
−
| KNX_DPT_FORMAT_B1U3        | bit fields to be computed by user application        |
 
−
| KNX_DPT_FORMAT_A8          |                                                      |
 
−
| KNX_DPT_FORMAT_U8          |                                                      |
 
−
| KNX_DPT_FORMAT_V8          |                                                      |
 
−
| KNX_DPT_FORMAT_B5N3        | bit fields to be computed by user application        |
 
−
| KNX_DPT_FORMAT_U16          |                                                      |
 
−
| KNX_DPT_FORMAT_V16          |                                                      |
 
−
| KNX_DPT_FORMAT_F16          |                                                      |
 
−
| KNX_DPT_FORMAT_U32          |                                                      |
 
−
| KNX_DPT_FORMAT_V32          |                                                      |
 
−
| KNX_DPT_FORMAT_F32          | **!!not yet implemented!!**                          |
 
  
−
___
 
−
**`e_KnxDeviceStatus Knx.read(byte objectIndex, byte returnedValue[]);`**
 
  
−
  _Read ANY format com object (advised to advanced users only)_
+
----
  
−
* **Description:** read the value of a group object. This function supports ALL the DPT formats, the returned value has a rough DPT format.
+
Update any usual format com object
−
___
 
−
**`e_KnxDeviceStatus Knx.write(byte objectIndex, <any standard C type> value);`**
 
  
−
  _Update any usual format com object_
+
<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.write(byte objectIndex, <any standard C type> value);</syntaxhighlight>
  
−
* **Description:** update the value of a group object. This function is relevant for objects with usual format, see table below.
+
'''Description:''' update the value of a group object. This function is relevant for objects with usual format, see table below.
 
In case the object has COMMUNICATION and TRANSMIT flags set, then a telegram is emitted on the EIB bus, thus the new value is propagated to the other devices.
 
In case the object has COMMUNICATION and TRANSMIT flags set, then a telegram is emitted on the EIB bus, thus the new value is propagated to the other devices.
−
* **Parameters:** "objectIndex" is the index (in the list) of the object to be updated. "value" is the new value. value can be any standard C type (boolean, uchar, char, uint, int, ulong, long, float, double types).
+
 
−
* **Return:** KNX_DEVICE_OK (0) when everything went well, KNX_DEVICE_NOT_IMPLEMENTED (254) in case of F32 conversion, KNX_DEVICE_ERROR (255) in case of unsupported group object format.
+
'''Parameters:''' "objectIndex" is the index (in the list) of the object to be updated. "value" is the new value. value can be any standard C type (boolean, uchar, char, uint, int, ulong, long, float, double types).
−
* **Examples:**
+
 
−
```
+
'''Return:''' KNX_DEVICE_OK (0) when everything went well, KNX_DEVICE_NOT_IMPLEMENTED (254) in case of F32 conversion, KNX_DEVICE_ERROR (255) in case of unsupported group object format.
 +
 
 +
'''Examples:'''
 +
 
 +
<syntaxhighlight lang="c++" line>
 
byte i=100; Knx.write(0,i); // the object with index 0 gets value 100
 
byte i=100; Knx.write(0,i); // the object with index 0 gets value 100
 
int j=-1000; Knx.write(1,j); // the object with index 1 gets value -1000
 
int j=-1000; Knx.write(1,j); // the object with index 1 gets value -1000
 
float k=1234.56; Knx.write(2,k); // the object with index 3 gets value 1234.56
 
float k=1234.56; Knx.write(2,k); // the object with index 3 gets value 1234.56
−
```
+
</syntaxhighlight>
 +
 
 +
{| class="wikitable" style="text-align:center"
 +
!Supported KNX DPT formats
 +
!Remark
 +
|-
 +
|KNX_DPT_FORMAT_B1
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B2
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B1U3
 +
|bit fields to be computed by user application
 +
|-
 +
|KNX_DPT_FORMAT_A8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_U8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V8
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_B5N3
 +
|bit fields to be computed by user application
 +
|-
 +
|KNX_DPT_FORMAT_U16
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V16
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_F16
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_U32
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_V32
 +
|
 +
|-
 +
|KNX_DPT_FORMAT_F32
 +
|''!!not yet implemented!!''
 +
|}
 +
 
 +
 
 +
----
 +
 
 +
 
 +
Update ANY format com object (advised to advanced users only)
 +
 
 +
<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.write(byte objectIndex, byte value[]);</syntaxhighlight>
 +
 
  
−
| supported KNX DPT formats   |        Remark                                      |
+
'''Description:''' update the value of a group object. This function supports ALL the DPT formats, but a rough DPT format value (previously computed by user application) shall be provided.
−
|:---------------------------:|:----------------------------------------------------:|
 
−
| KNX_DPT_FORMAT_B1          |                                                      |
 
−
| KNX_DPT_FORMAT_B2          |                                                      |
 
−
| KNX_DPT_FORMAT_B1U3        | bit fields to be computed by user application       |
 
−
| KNX_DPT_FORMAT_A8          |                                                      |
 
−
| KNX_DPT_FORMAT_U8          |                                                      |
 
−
| KNX_DPT_FORMAT_V8          |                                                      |
 
−
| KNX_DPT_FORMAT_B5N3        | bit fields to be computed by user application        |
 
−
| KNX_DPT_FORMAT_U16          |                                                      |
 
−
| KNX_DPT_FORMAT_V16          |                                                      |
 
−
| KNX_DPT_FORMAT_F16          |                                                      |
 
−
| KNX_DPT_FORMAT_U32          |                                                      |
 
−
| KNX_DPT_FORMAT_V32          |                                                      |
 
−
| KNX_DPT_FORMAT_F32          | **!!not yet implemented!!**                          |
 
  
  
−
___
+
----
−
**`e_KnxDeviceStatus Knx.write(byte objectIndex, byte value[]);`**
 
  
−
  _Update ANY format com object (advised to advanced users only)_
 
  
−
* **Description:** update the value of a group object. This function supports ALL the DPT formats, but a rough DPT format value (previously computed by user application) shall be provided.
+
<syntaxhighlight lang="c++" inline>void Knx.update(byte objectIndex);</syntaxhighlight>
−
___
 
−
**`void Knx.update(byte objectIndex);`**
 
  
 
   _Request the local object value to be updated via the bus_
 
   _Request the local object value to be updated via the bus_
  
−
* **Description:** request the (local) group object value to be updated with the value from the bus. Note that this function is _asynchroneous_, the update completion is notified by the knxEvents() callback. This function is relevant only for objects with UPDATE and TRANSMIT flags set.
+
'''Description:''' request the (local) group object value to be updated with the value from the bus. Note that this function is _asynchroneous_, the update completion is notified by the knxEvents() callback. This function is relevant only for objects with UPDATE and TRANSMIT flags set.
−
* **Parameters:** "objectIndex" is the index (in the list) of the object to be updated.  
+
'''Parameters:''' "objectIndex" is the index (in the list) of the object to be updated.  
−
* **Example:** ```Knx.update(0); // request the update of the object with index 0.```
+
'''Example:''' <syntaxhighlight lang="c++" inline>Knx.update(0); // request the update of the object with index 0.</syntaxhighlight>
 +
 
  
 +
==== Working with the device ====
  
−
==== 4/ Working with the device ====
+
<syntaxhighlight lang="c++" inline>bool isFactorySetting();</syntaxhighlight>
−
___
+
'''Description:''' Returns the current device state. Use this before asking for device parameters. If is factory setting, parameters are not yet initialized and do not contain valid values!   
−
**`bool isFactorySetting();`**
 
−
* **Description:** Returns the current device state. Use this before asking for device parameters. If is factory setting, parameters are not yet initialized and do not contain valid values!   
 
  
−
* **Example:**
+
'''Example:'''
−
```
+
 
 +
<syntaxhighlight lang="c++" line>
 
if (!Konnekting.isFactorySetting()) {
 
if (!Konnekting.isFactorySetting()) {
 
     // now you can be sure that device params contain valid values
 
     // now you can be sure that device params contain valid values
 
}
 
}
−
```
+
</syntaxhighlight>
  
−
___
 
−
**`uint8_t getUINT8Param(byte index);`** 
 
−
**`int8_t getINT8Param(byte index);`** 
 
−
**`uint16_t getUINT16Param(byte index);`** 
 
−
**`int16_t getINT16Param(byte index);`** 
 
−
**`uint32_t getUINT32Param(byte index);`** 
 
−
**`int32_t getINT32Param(byte index);`** 
 
−
* **Description:**  Returns the parameter value which has been programmed via the KONNEKTING Suite. You have to make sure you use the method that matches the parameter type (UINT8, INT8, UNINT16, ...). Otherwise you will get an 0-value.
 
−
* **Parameters:** "index" is the ID of your parameter, as it is defined in the [.knxdevice.xml](/konnekting_xml_device_description.md).
 
  
−
* **Example:**
+
----
−
```
+
 
 +
 
 +
<syntaxhighlight lang="c++" line>
 +
uint8_t getUINT8Param(byte index);
 +
int8_t getINT8Param(byte index);
 +
uint16_t getUINT16Param(byte index);
 +
int16_t getINT16Param(byte index);
 +
uint32_t getUINT32Param(byte index);
 +
int32_t getINT32Param(byte index);
 +
</syntaxhighlight>
 +
 +
'''Description:'''  Returns the parameter value which has been programmed via the KONNEKTING Suite. You have to make sure you use the method that matches the parameter type (UINT8, INT8, UNINT16, ...). Otherwise you will get an 0-value.
 +
'''Parameters:''' "index" is the ID of your parameter, as it is defined in the [.knxdevice.xml](/konnekting_xml_device_description.md).
 +
 
 +
'''Example:'''
 +
<syntaxhighlight lang="c++" line>
 
byte myUINT8Param = Konnekting.getUINT8Param(0);
 
byte myUINT8Param = Konnekting.getUINT8Param(0);
 
signed int myINT8Param = Konnekting.getINT8Param(1);
 
signed int myINT8Param = Konnekting.getINT8Param(1);
Line 325: Line 463:
 
long myINT32Param = Konnekting.getINT32Param(4);
 
long myINT32Param = Konnekting.getINT32Param(4);
 
unsigned long myUINT32Param = Konnekting.getUINT32Param(5);
 
unsigned long myUINT32Param = Konnekting.getUINT32Param(5);
−
```
+
</syntaxhighlight>
 +
 
 +
----
  
−
___
+
<syntaxhighlight lang="c++" inline>bool isReadyForApplication();</syntaxhighlight>
−
**`bool isReadyForApplication();`**
+
'''Description:''' Returns the current ready state of the device. You should use this to suspend sketch action (reading sensors etc.) while device is not ready for application (e.g. in programming mode, ...).  
−
* **Description:** Returns the current ready state of the device. You should use this to suspend sketch action (reading sensors etc.) while device is not ready for application (e.g. in programming mode, ...).  
+
'''Example:'''
−
* **Example:**
+
<syntaxhighlight lang="c++" line>
−
```
 
 
if (Konnekting.isReadyForApplication()) {
 
if (Konnekting.isReadyForApplication()) {
 
     // do whatever is required for your device, reading sensors, procession I/O, ...
 
     // do whatever is required for your device, reading sensors, procession I/O, ...
 
}
 
}
−
```
+
</syntaxhighlight>
  
 +
----
  
−
___
+
<syntaxhighlight lang="c++" inline>int getFreeEepromOffset();</syntaxhighlight>
−
**`int getFreeEepromOffset();`**
+
 
−
* **Description:** Returns an EEPROM index offset, at which it is save to read/store your device related data. **WARNING: Don't write in the area in front of this index. YOU WILL BREAK YOUR COM-OBJECTS AND DEVICE PARAMETER DATA!!!**
+
'''Description:''' Returns an EEPROM index offset, at which it is save to read/store your device related data.  
−
* **Example:**
+
 
−
```
+
'''WARNING: Don't write in the area in front of this index. YOU WILL BREAK YOUR COM-OBJECTS AND DEVICE PARAMETER DATA!!!'''
 +
 
 +
'''Example:'''
 +
 
 +
<syntaxhighlight lang="c++" line>
 
// writing a 4-byte value to EEPROM
 
// writing a 4-byte value to EEPROM
 
int freeEepromOffset = Konnekting.getFreeEepromOffset();
 
int freeEepromOffset = Konnekting.getFreeEepromOffset();
Line 349: Line 493:
 
EEPROM.write(freeEepromOffset+2, myData[2]);
 
EEPROM.write(freeEepromOffset+2, myData[2]);
 
EEPROM.write(freeEepromOffset+3, myData[3]);
 
EEPROM.write(freeEepromOffset+3, myData[3]);
−
```
+
</syntaxhighlight>

Latest revision as of 16:13, 22 March 2018

Hardware Requirements

(*)deprecated = will be sonner or later "dropped" and not actively supported/maintained

Other (Arduino compatible) controllers might work as well. But don't expect that they work flawlessly without adapting our library code. We try to keep the number of directly supported controllers short, so that the overall maintenance is easy. We don't want to add dozens of if-else-compiler-flags to support each and every available microcontroller. You can do this by yourself. But please accept that this will not be merged in the public code (maintenance ...)

You need at least two free pins on the microcontroller for

  • Programming Button
  • Programming LED

It is required, that the programming button is connected to a pin on the microcontroller which is capable of a real harwdare interrupt. Internally we use the attachInterrupt() Arduino function (https://www.arduino.cc/en/Reference/attachInterrupt). So make sure your button is connected to a pin that is supported by this function.

The pin on the microcontroller for the LED can be any digital output pin.

KONNEKTING XML Device Description ".kdevice.xml"

KONNEKTING Device Library

The device library enables the Arduino to connect to the KNX bus.

Example Sketch Explained

 1// include KnxDevice library
 2#include <KnxDevice.h>
 3
 4// Set the device identification
 5#define MANUFACTURER_ID 12345
 6#define DEVICE_ID 123
 7#define Revision 0
 8
 9// Set Prog-LED Pin and Prog-Button Pin
10#define PROG_LED_PIN LED_BUILTIN  
11#define PROG_BUTTON_PIN 3
12
13// Set KNX Transceiver serial port
14#ifdef __AVR_ATmega328P__
15#define KNX_SERIAL Serial // Nano/ProMini etc. use Serial
16#else
17#define KNX_SERIAL Serial1 // Leonardo/Micro etc. use Serial1
18#endif
19
20// ----------------------------
21
22// Definition of the Communication Objects attached to the device
23KnxComObject KnxDevice::_comObjectsList[] = {
24    
25    /* ComObject ID 0 : Your first com object, referenced in your device XML */ 
26    KnxComObject(KNX_DPT_1_001, COM_OBJ_LOGIC_IN),
27    
28    /* ComObject ID 1 */ 
29    KnxComObject(KNX_DPT_1_001, COM_OBJ_SENSOR),
30    
31    // more com objects if you need ...
32};
33const byte KnxDevice::_numberOfComObjects = sizeof (_comObjectsList) / sizeof (KnxComObject); // do no change this code
34
35// Definition of parameter size / type ...
36// Ensure that this matches your parameter configuration in your device XML
37byte KonnektingDevice::_paramSizeList[] = {
38
39    /* Param Index 0 */ PARAM_UINT8,
40    /* Param Index 1 */ PARAM_INT16,
41    /* Param Index 2 */ PARAM_UINT32,
42    
43    // more parameters if you need
44};
45const byte KonnektingDevice::_numberOfParams = sizeof (_paramSizeList); // do no change this code
46
47
48
49// Callback function to handle com objects updates
50void knxEvents(byte index) {
51    
52    // index will contain the com-object which received a telegram
53    // Do what ever is needed
54    
55};
56
57void setup() {
58
59    // Initialize KNX enabled Arduino Board
60    Konnekting.init(KNX_SERIAL, 
61              PROG_BUTTON_PIN, 
62              PROG_LED_PIN, 
63              MANUFACTURER_ID, 
64              DEVICE_ID, 
65              REVISION);
66              
67    if (!Konnekting.isFactorySetting()) {
68        
69        // you can access your parameters by callig
70        byte paramId0 = Konnekting.getUINT8Param(0);
71    
72        // There's a getXXXXParam method for each known parameter type
73    }
74}
75
76void loop() {
77    // handle KNX stuff
78    Knx.task();
79    if (Konnekting.isReadyForApplication()) {
80        // do device related stuff
81    }
82}

API

Instead of explaining method by method without any context, we try to explain the code and the API with an step by step approach.

Define the communication objects

First of all, define the KNX communication objects of your bus device. For each object, define its datapoint type, and its flags. Theoritically, you can define up to 255 objects, even if in practical you are limited by the quantity of RAM (it would be worth measuring the max allowed number of objects depending on the memory available).

KnxComObject KnxDevice::_comObjectsList[];

Description: list of the communication objects (group objects) that are attached to your KNX device. Define this variable in your Arduino sketch (but outside all function bodies).

Parameters: for each object in the list, you shall provide the group address (word, use G_ADDR() function), the datapoint type (check "_e_KnxDPT_ID_" enum in KnxDPT.h file), and the flags (byte, check KnxComObject.h for more details).

Example: 

1//           DataPointType						                	flags			
2KnxComObject{KNX_DPT_1_001 /* 1.001 B1 DPT_Switch */ ,	          COM_OBJ_LOGIC_IN_INIT	} 
3KnxComObject{KNX_DPT_5_010 /* 5.010 U8 DPT_Value_1_Ucount */ ,	  COM_OBJ_SENSOR		} 
4KnxComObject{KNX_DPT_1_003 /* 1.003 B1 DPT_Enable*/ ,		      0x30 /* C+R */		}



const byte KnxDevice::_comObjectsNb = sizeof(_comObjectsList) / sizeof(KnxComObject);

Description: Define the number of group objects in the list. Simply copy the above code as is in your Arduino sketch!

Init KNX device

void init(HardwareSerial& serial, int progButtonPin, int progLedPin, word manufacturerID, byte deviceID, byte revisionID);

Description: Start the KNX Device. Place this function call in the setup() function of your Arduino sketch

Parameters: serial = serial port that is connected to the KNX TPUART Transceiver, progButtonPin = arduino pin which is connected to the prog button and **is capable of an real interrupt**, progLedPin = arduino pin which is connected to the programming LED, [manufacturerID = your manufacturer ID](konnekting_manufacturers.md), deviceID = ID identifying your device, revision = revision of your firmware (increment if new version is no longer backwards-compatible)

Example: 

1Konnekting.init(KNX_SERIAL, 
2              PROG_BUTTON_PIN, 
3              PROG_LED_PIN, 
4              MANUFACTURER_ID, 
5              DEVICE_ID, 
6              REVISION);



void task(void);

Description: KNX device execution task. This function call shall be placed in the "loop()" Arduino function.

WARNING: this function shall be called periodically (400us max period) meaning usage of functions stopping the execution (like delay(), visit http://playground.arduino.cc/Code/AvoidDelay for more info) is FORBIDDEN.

Example: 

1Knx.task();


Interact with the communication objects

The API allows you to interact with objects that you have defined : you can read and modify their values, force their value to be updated with the value on the bus. You are also notified each time objects get their value changed following a bus access :

void knxEvents(byte objectIndex);

Description: callback function that is called by the KnxDevice library every time a group object is updated by the bus. Define this function in your Arduino sketch.

Parameters : "objectIndex" is the index (in the list) of the object updated by the bus

Example: 

 1// Callback function to treat object updates
 2void knxEvents(byte index) {
 3  switch (index)
 4  {
 5    case 0 : // we arrive here when object index 0 has been updated
 6      // code to treat index 0 object update
 7      break;
 8
 9    case 1 : // we arrive here when object index 1 has been updaed
10      // code to treat index 1 object update
11      break;
12
13//  ...
14
15    default:
16      // code to treat remaining objects updates
17      break;
18  }
19};


Quick method to get the value of a short object:

byte Knx.read(byte objectIndex);

Description: Get the current value of a short group object. This function is relevant for _short_ objects only, see table below. The returned value will be hazardous in case of use with _long_ objects.

Parameters: "objectIndex" is the index (in the list) of the object to be read.

Return: the current value of the object.

Example: 

1Knx.read(0); // return index 0 object value
Supported KNX DPT formats Remark
KNX_DPT_FORMAT_B1
KNX_DPT_FORMAT_B2
KNX_DPT_FORMAT_B1U3 bit fields to be computed by user application
KNX_DPT_FORMAT_A8
KNX_DPT_FORMAT_U8
KNX_DPT_FORMAT_V8
KNX_DPT_FORMAT_B5N3 bit fields to be computed by user application


Read an usual format com object

e_KnxDeviceStatus Knx.read(byte objectIndex, <any standard C type>& returnedValue);

Description: Get the current value of a group object. This function is relevant for objects with usual format, see table below.

Parameters: "objectIndex" is the index (in the list) of the object to be read. "returnedValue" is the read com object value. "returnedValue" can be any standard C type (boolean, uchar, char, uint, int, ulong, long, float, double types).

Return: KNX_DEVICE_OK (0) when everything went well, KNX_DEVICE_NOT_IMPLEMENTED (254) in case of F32 conversion, KNX_DEVICE_ERROR (255) in case of unsupported group object format.

Examples: 

1byte i; Knx.read(0,i); // read index 0 object (short object)
2unsigned int j; Knx.read(1,j); // read index 1 object (U16 format)
3int k; Knx.read(2,k); // read index 2 object (V16 format)
4unsigned long l; Knx.read(3,l); // read index 3 object (U32 format)
5long m; Knx.read(4,m); // read index 4 object (V32 format)
6float n; Knx.read(5,n); // read index 5 object (F16/F32 format)
Supported KNX DPT formats Remark
KNX_DPT_FORMAT_B1
KNX_DPT_FORMAT_B2
KNX_DPT_FORMAT_B1U3 bit fields to be computed by user application
KNX_DPT_FORMAT_A8
KNX_DPT_FORMAT_U8
KNX_DPT_FORMAT_V8
KNX_DPT_FORMAT_B5N3 bit fields to be computed by user application
KNX_DPT_FORMAT_U16
KNX_DPT_FORMAT_V16
KNX_DPT_FORMAT_F16
KNX_DPT_FORMAT_U32
KNX_DPT_FORMAT_V32
KNX_DPT_FORMAT_F32 !!not yet implemented!!


Read ANY format com object (advised to advanced users only)

e_KnxDeviceStatus Knx.read(byte objectIndex, byte returnedValue[]);

Description: read the value of a group object. This function supports ALL the DPT formats, the returned value has a rough DPT format.


Update any usual format com object

e_KnxDeviceStatus Knx.write(byte objectIndex, <any standard C type> value);

Description: update the value of a group object. This function is relevant for objects with usual format, see table below. In case the object has COMMUNICATION and TRANSMIT flags set, then a telegram is emitted on the EIB bus, thus the new value is propagated to the other devices.

Parameters: "objectIndex" is the index (in the list) of the object to be updated. "value" is the new value. value can be any standard C type (boolean, uchar, char, uint, int, ulong, long, float, double types).

Return: KNX_DEVICE_OK (0) when everything went well, KNX_DEVICE_NOT_IMPLEMENTED (254) in case of F32 conversion, KNX_DEVICE_ERROR (255) in case of unsupported group object format.

Examples: 

1byte i=100; Knx.write(0,i); // the object with index 0 gets value 100
2int j=-1000; Knx.write(1,j); // the object with index 1 gets value -1000
3float k=1234.56; Knx.write(2,k); // the object with index 3 gets value 1234.56
Supported KNX DPT formats Remark
KNX_DPT_FORMAT_B1
KNX_DPT_FORMAT_B2
KNX_DPT_FORMAT_B1U3 bit fields to be computed by user application
KNX_DPT_FORMAT_A8
KNX_DPT_FORMAT_U8
KNX_DPT_FORMAT_V8
KNX_DPT_FORMAT_B5N3 bit fields to be computed by user application
KNX_DPT_FORMAT_U16
KNX_DPT_FORMAT_V16
KNX_DPT_FORMAT_F16
KNX_DPT_FORMAT_U32
KNX_DPT_FORMAT_V32
KNX_DPT_FORMAT_F32 !!not yet implemented!!



Update ANY format com object (advised to advanced users only)

e_KnxDeviceStatus Knx.write(byte objectIndex, byte value[]);


Description: update the value of a group object. This function supports ALL the DPT formats, but a rough DPT format value (previously computed by user application) shall be provided.



void Knx.update(byte objectIndex); 

 _Request the local object value to be updated via the bus_

Description: request the (local) group object value to be updated with the value from the bus. Note that this function is _asynchroneous_, the update completion is notified by the knxEvents() callback. This function is relevant only for objects with UPDATE and TRANSMIT flags set. Parameters: "objectIndex" is the index (in the list) of the object to be updated. Example: Knx.update(0); // request the update of the object with index 0.


Working with the device

bool isFactorySetting(); Description: Returns the current device state. Use this before asking for device parameters. If is factory setting, parameters are not yet initialized and do not contain valid values!

Example: 

1if (!Konnekting.isFactorySetting()) {
2    // now you can be sure that device params contain valid values
3}




1uint8_t getUINT8Param(byte index);
2int8_t getINT8Param(byte index);
3uint16_t getUINT16Param(byte index);
4int16_t getINT16Param(byte index);
5uint32_t getUINT32Param(byte index);
6int32_t getINT32Param(byte index);

Description: Returns the parameter value which has been programmed via the KONNEKTING Suite. You have to make sure you use the method that matches the parameter type (UINT8, INT8, UNINT16, ...). Otherwise you will get an 0-value. Parameters: "index" is the ID of your parameter, as it is defined in the [.knxdevice.xml](/konnekting_xml_device_description.md).

Example: 

1byte myUINT8Param = Konnekting.getUINT8Param(0);
2signed int myINT8Param = Konnekting.getINT8Param(1);
3
4int myINT16Param = Konnekting.getINT16Param(2);
5unsigned int myUINT16Param = Konnekting.getUINT16Param(3);
6
7long myINT32Param = Konnekting.getINT32Param(4);
8unsigned long myUINT32Param = Konnekting.getUINT32Param(5);

bool isReadyForApplication(); Description: Returns the current ready state of the device. You should use this to suspend sketch action (reading sensors etc.) while device is not ready for application (e.g. in programming mode, ...). Example: 

1if (Konnekting.isReadyForApplication()) {
2    // do whatever is required for your device, reading sensors, procession I/O, ...
3}

int getFreeEepromOffset();

Description: Returns an EEPROM index offset, at which it is save to read/store your device related data.

WARNING: Don't write in the area in front of this index. YOU WILL BREAK YOUR COM-OBJECTS AND DEVICE PARAMETER DATA!!!

Example: 

1// writing a 4-byte value to EEPROM
2int freeEepromOffset = Konnekting.getFreeEepromOffset();
3EEPROM.write(freeEepromOffset, myData[0]);
4EEPROM.write(freeEepromOffset+1, myData[1]);
5EEPROM.write(freeEepromOffset+2, myData[2]);
6EEPROM.write(freeEepromOffset+3, myData[3]);
Retrieved from "http://wiki.konnekting.de/index.php?title=KONNEKTING_Device_Library&oldid=390"