KONNEKTING Device Library - Revision history

Konnekting at 16:13, 22 March 2018

2018-03-22T16:13:08Z

Konnekting at 16:08, 22 March 2018

2018-03-22T16:08:21Z

Konnekting: /* Hardware Requirements */

2018-03-07T09:30:31Z

Hardware Requirements

Konnekting at 10:12, 16 February 2018

2018-02-16T10:12:09Z

Show changes

Konnekting: /* Supported microcontrollers */

2018-02-16T10:01:25Z

Supported microcontrollers

Konnekting at 14:34, 15 February 2018

2018-02-15T14:34:03Z

Konnekting at 14:30, 15 February 2018

2018-02-15T14:30:36Z

Konnekting at 14:27, 15 February 2018

2018-02-15T14:27:31Z

Konnekting at 14:20, 15 February 2018

2018-02-15T14:20:54Z

Konnekting at 14:20, 15 February 2018

2018-02-15T14:20:00Z

@@ Line 230: / Line 230: @@
 ----
 {| class="wikitable" style="text-align:center"
@@ Line 303: / Line 281: @@
 </syntaxhighlight>
-| supported KNX DPT formats   |         Remark                                       |
+{| class="wikitable" style="text-align:center"
-|:---------------------------:|:----------------------------------------------------:|
+!Supported KNX DPT formats
-| KNX_DPT_FORMAT_B1           |                                                      |
+!Remark
-| KNX_DPT_FORMAT_B2           |                                                      |
+|-
-| KNX_DPT_FORMAT_B1U3         | bit fields to be computed by user application        |
+|KNX_DPT_FORMAT_B1
-| KNX_DPT_FORMAT_A8           |                                                      |
-| KNX_DPT_FORMAT_U8           |                                                      |
+|-
-| KNX_DPT_FORMAT_V8           |                                                      |
+|KNX_DPT_FORMAT_B2
-| KNX_DPT_FORMAT_B5N3         | bit fields to be computed by user application        |
-| KNX_DPT_FORMAT_U16          |                                                      |
+|-
-| KNX_DPT_FORMAT_V16          |                                                      |
+|KNX_DPT_FORMAT_B1U3
-| KNX_DPT_FORMAT_F16          |                                                      |
+|bit fields to be computed by user application
-| KNX_DPT_FORMAT_U32          |                                                      |
+|-
-| KNX_DPT_FORMAT_V32          |                                                      |
+|KNX_DPT_FORMAT_A8
-| KNX_DPT_FORMAT_F32          | **!!not yet implemented!!**                          |
@@ Line 350: / Line 356: @@
 </syntaxhighlight>
-| supported KNX DPT formats   |         Remark                                       |
+{| class="wikitable" style="text-align:center"
-|:---------------------------:|:----------------------------------------------------:|
+!Supported KNX DPT formats
-| KNX_DPT_FORMAT_B1           |                                                      |
+!Remark
-| KNX_DPT_FORMAT_B2           |                                                      |
+|-
-| KNX_DPT_FORMAT_B1U3         | bit fields to be computed by user application        |
+|KNX_DPT_FORMAT_B1
-| KNX_DPT_FORMAT_A8           |                                                      |
-| KNX_DPT_FORMAT_U8           |                                                      |
+|-
-| KNX_DPT_FORMAT_V8           |                                                      |
+|KNX_DPT_FORMAT_B2
-| KNX_DPT_FORMAT_B5N3         | bit fields to be computed by user application        |
-| KNX_DPT_FORMAT_U16          |                                                      |
+|-
-| KNX_DPT_FORMAT_V16          |                                                      |
+|KNX_DPT_FORMAT_B1U3
-| KNX_DPT_FORMAT_F16          |                                                      |
+|bit fields to be computed by user application
-| KNX_DPT_FORMAT_U32          |                                                      |
+|-
-| KNX_DPT_FORMAT_V32          |                                                      |
+|KNX_DPT_FORMAT_A8
-| KNX_DPT_FORMAT_F32          | **!!not yet implemented!!**                          |

@@ Line 231: / Line 231: @@
 ----
-| supported KNX DPT formats   |         Remark                                       |
+{| class="wikitable" style="text-align:center"
-|:---------------------------:|:----------------------------------------------------:|
+!Byte no#:
-| KNX_DPT_FORMAT_B1           |                                                      |
+!0
-| KNX_DPT_FORMAT_B2           |                                                      |
+!1
-| KNX_DPT_FORMAT_B1U3         | bit fields to be computed by user application        |
+!2
-| KNX_DPT_FORMAT_A8           |                                                      |
+!...
-| KNX_DPT_FORMAT_U8           |                                                      |
+!13
-| KNX_DPT_FORMAT_V8           |                                                      |
+|-
-| KNX_DPT_FORMAT_B5N3         | bit fields to be computed by user application        |
+!Used for:
 ----

@@ Line 1: / Line 1: @@
 == 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
-(*)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.
 [[KONNEKTING_XML_Device_Description | KONNEKTING XML Device Description ".kdevice.xml"]]

← Older revision		Revision as of 10:01, 16 February 2018
Line 1:		Line 1:
−	== ~~Supported microcontrollers~~ ==	+	== Hardware Requirements ==

	* Atmel SAMD21G18J		* Atmel SAMD21G18J

@@ Line 233: / Line 233: @@
 '''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; Knx.read(0,i); // read index 0 object (short object)
 unsigned int j; Knx.read(1,j); // read index 1 object (U16 format)
@@ Line 240: / Line 240: @@
 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)
-```
+</syntaxhighlight>
 | supported KNX DPT formats   |         Remark                                       |
@@ Line 274: / Line 274: @@
 '''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
 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
-```
+</syntaxhighlight>
 | supported KNX DPT formats   |         Remark                                       |
@@ Line 310: / Line 310: @@
 '''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.```
+'''Example:''' <syntaxhighlight lang="c++" inline>Knx.update(0); // request the update of the object with index 0.</syntaxhighlight>
@@ Line 319: / Line 319: @@
 '''Example:'''
-```
+<syntaxhighlight lang="c++" line>
 if (!Konnekting.isFactorySetting()) {
      // now you can be sure that device params contain valid values
+}
-```
+</syntaxhighlight>
 ___
@@ Line 336: / Line 336: @@
 '''Example:'''
-```
+<syntaxhighlight lang="c++" line>
 byte myUINT8Param = Konnekting.getUINT8Param(0);
 signed int myINT8Param = Konnekting.getINT8Param(1);
@@ Line 345: / Line 345: @@
 long myINT32Param = Konnekting.getINT32Param(4);
 unsigned long myUINT32Param = Konnekting.getUINT32Param(5);
-```
+</syntaxhighlight>
 ___
@@ Line 351: / Line 351: @@
 '''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:'''
-```
+<syntaxhighlight lang="c++" line>
 if (Konnekting.isReadyForApplication()) {
      // do whatever is required for your device, reading sensors, procession I/O, ...
+}
-```
+</syntaxhighlight>
@@ Line 362: / Line 362: @@
 '''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:'''
-```
+<syntaxhighlight lang="c++" line>
 // writing a 4-byte value to EEPROM
 int freeEepromOffset = Konnekting.getFreeEepromOffset();
@@ Line 369: / Line 369: @@
 EEPROM.write(freeEepromOffset+2, myData[2]);
 EEPROM.write(freeEepromOffset+3, myData[3]);
-```
+</syntaxhighlight>

@@ Line 225: / Line 225: @@
 ___
-**`e_KnxDeviceStatus Knx.read(byte objectIndex, <any standard C type>& returnedValue);`**
+<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.read(byte objectIndex, <any standard C type>& returnedValue);</syntaxhighlight>
    _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.
+'''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).
+'''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.
+'''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:**
+'''Examples:'''
 ```
 byte i; Knx.read(0,i); // read index 0 object (short object)
@@ Line 259: / Line 259: @@
 ___
-**`e_KnxDeviceStatus Knx.read(byte objectIndex, byte returnedValue[]);`**
+<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.read(byte objectIndex, byte returnedValue[]);</syntaxhighlight>
    _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.
+'''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);`**
+<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.write(byte objectIndex, <any standard C type> value);</syntaxhighlight>
    _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.
+'''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).
+'''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.
+'''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:**
+'''Examples:'''
 ```
 byte i=100; Knx.write(0,i); // the object with index 0 gets value 100
@@ Line 298: / Line 298: @@
 ___
-**`e_KnxDeviceStatus Knx.write(byte objectIndex, byte value[]);`**
+<syntaxhighlight lang="c++" inline>e_KnxDeviceStatus Knx.write(byte objectIndex, byte value[]);</syntaxhighlight>
    _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.
+'''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);`**
+<syntaxhighlight lang="c++" inline>void Knx.update(byte objectIndex);</syntaxhighlight>
    _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:''' ```Knx.update(0); // request the update of the object with index 0.```
 ==== 4/ Working with the device ====
 ___
-**`bool isFactorySetting();`**
+<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!
+'''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:'''
 ```
 if (!Konnekting.isFactorySetting()) {
@@ Line 326: / Line 326: @@
 ___
-**`uint8_t getUINT8Param(byte index);`**
+<syntaxhighlight lang="c++" inline>uint8_t getUINT8Param(byte index);</syntaxhighlight>
-**`int8_t getINT8Param(byte index);`**
+<syntaxhighlight lang="c++" inline>int8_t getINT8Param(byte index);</syntaxhighlight>
-**`uint16_t getUINT16Param(byte index);`**
+<syntaxhighlight lang="c++" inline>uint16_t getUINT16Param(byte index);</syntaxhighlight>
-**`int16_t getINT16Param(byte index);`**
+<syntaxhighlight lang="c++" inline>int16_t getINT16Param(byte index);</syntaxhighlight>
-**`uint32_t getUINT32Param(byte index);`**
+<syntaxhighlight lang="c++" inline>uint32_t getUINT32Param(byte index);</syntaxhighlight>
-**`int32_t getINT32Param(byte index);`**
+<syntaxhighlight lang="c++" inline>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.
+'''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).
+'''Parameters:''' "index" is the ID of your parameter, as it is defined in the [.knxdevice.xml](/konnekting_xml_device_description.md).
-* **Example:**
+'''Example:'''
 ```
 byte myUINT8Param = Konnekting.getUINT8Param(0);
@@ Line 348: / Line 348: @@
 ___
-**`bool isReadyForApplication();`**
+<syntaxhighlight lang="c++" inline>bool isReadyForApplication();</syntaxhighlight>
-* **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:'''
 ```
 if (Konnekting.isReadyForApplication()) {
@@ Line 359: / Line 359: @@
 ___
-**`int getFreeEepromOffset();`**
+<syntaxhighlight lang="c++" inline>int getFreeEepromOffset();</syntaxhighlight>
-* **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. **WARNING: Don't write in the area in front of this index. YOU WILL BREAK YOUR COM-OBJECTS AND DEVICE PARAMETER DATA!!!**
-* **Example:**
+'''Example:'''
 ```
 // writing a 4-byte value to EEPROM

@@ Line 106: / Line 106: @@
 === API ===
 ==== Define the communication objects ====
@@ Line 160: / Line 162: @@
 </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 :
-  _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.
+<syntaxhighlight lang="c++" line>
 // Callback function to treat object updates
 void knxEvents(byte index) {
@@ Line 191: / Line 195: @@
+   }
 };
-```
+</syntaxhighlight>
-___
+'''Example:'''
-  _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.
+----
 | supported KNX DPT formats   |         Remark                                       |

@@ Line 14: / Line 14: @@
 -----
-== KONNEKTING Device Library
+== KONNEKTING Device Library ==
 The device library enables the Arduino to connect to the KNX bus.
-=== Example Sketch Explained
+=== Example Sketch Explained ===
 <syntaxhighlight lang=c++ line>

@@ Line 106: / Line 106: @@
 === API ===
-==== 1 / 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).
@@ Line 113: / Line 114: @@
 '''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).
 '''Example:'''
@@ Line 123: / Line 125: @@
 KnxComObject{KNX_DPT_1_003 /* 1.003 B1 DPT_Enable*/ ,		      0x30 /* C+R */		}
 </syntaxhighlight>
-==== 2/ Init KNX device ====
+<syntaxhighlight lang="c++" inline>const byte KnxDevice::_comObjectsNb = sizeof(_comObjectsList) / sizeof(KnxComObject);</syntaxhighlight>
-___
-**`void init(HardwareSerial& serial, int progButtonPin, int progLedPin, word manufacturerID, byte deviceID, byte revisionID);`**
+'''Description:''' Define the number of group objects in the list. Simply copy the above code as is in your Arduino sketch!
-* **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)
+==== Init KNX device ====
-* **Example:**
+'''Example:'''
-```
+<syntaxhighlight lang="c++" line>
 Konnekting.init(KNX_SERIAL,
                PROG_BUTTON_PIN,
@@ Line 141: / Line 146: @@
                DEVICE_ID,
                REVISION);
-```
+</syntaxhighlight>
-___
+<syntaxhighlight lang="c++" line>
 Knx.task();
-```
+</syntaxhighlight>
 ___