Difference between revisions of "KONNEKTING Device Library"

From KONNEKTING Wiki
Jump to navigation Jump to search
Line 106: Line 106:
  
 
=== API ===
 
=== 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 ====
 
==== Define the communication objects ====
Line 160: Line 162:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
___
+
 
−
==== 3/ Interact with the communication objects ====
+
==== 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 191: Line 195:
 
   }
 
   }
 
};
 
};
−
```
+
</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:'''
−
**`byte Knx.read(byte objectIndex);`**
 
  
−
  _Quick method to get the value of a short object_
+
<syntaxhighlight lang="c++" line>Knx.read(0); // return index 0 object value</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:** ```Knx.read(0); // return index 0 object value```
 
  
 
| supported KNX DPT formats  |        Remark                                      |
 
| supported KNX DPT formats  |        Remark                                      |

Revision as of 14:27, 15 February 2018

Supported microcontrollers

  • Atmel SAMD21G18J
  • Atmel ATMega 328P (*deprecated)
  • Atmel ATMega 32U4 (*deprecated)
  • Espressiv ESP8266

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

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 |

___

    • `e_KnxDeviceStatus Knx.read(byte objectIndex, <any standard C type>& returnedValue);`**
 _Read an usual format com object_
  • **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:**

``` 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) int k; Knx.read(2,k); // read index 2 object (V16 format) unsigned long l; Knx.read(3,l); // read index 3 object (U32 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) ```

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

___

    • `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.

___

    • `e_KnxDeviceStatus Knx.write(byte objectIndex, <any standard C type> value);`**
 _Update any usual format com object_
  • **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:**

``` 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 float 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!!** |


___

    • `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.

___

    • `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.```


4/ 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:**

``` if (!Konnekting.isFactorySetting()) { 

   // now you can be sure that device params contain valid values

} ```

___

    • `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:**

``` byte myUINT8Param = Konnekting.getUINT8Param(0); signed int myINT8Param = Konnekting.getINT8Param(1);

int myINT16Param = Konnekting.getINT16Param(2); unsigned int myUINT16Param = Konnekting.getUINT16Param(3);

long myINT32Param = Konnekting.getINT32Param(4); unsigned 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:**

``` if (Konnekting.isReadyForApplication()) { 

   // do whatever is required for your device, reading sensors, procession I/O, ...

} ```


___

    • `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:**

``` // writing a 4-byte value to EEPROM int freeEepromOffset = Konnekting.getFreeEepromOffset(); EEPROM.write(freeEepromOffset, myData[0]); EEPROM.write(freeEepromOffset+1, myData[1]); EEPROM.write(freeEepromOffset+2, myData[2]); EEPROM.write(freeEepromOffset+3, myData[3]); ```

Retrieved from "http://wiki.konnekting.de/index.php?title=KONNEKTING_Device_Library&oldid=119"