smartserver-driver-template

Developers can create custom drivers for the SmartServer IoT using the custom driver template in this project. The procedure for developing a custom driver is described on this page. Additional documentation is available at https://edgedocs.enocean.com.

** This project requires SmartServer 3.4 or newer. **

To create and test a custom driver for the SmartServer follow these steps:

1. Open a Linux console for your SmartServer.
2. If the git application is not already installed, enter the following commands: sudo apt-get update sudo apt-get install -y git
3. Clone the IDL example at https://github.com/izot/smartserver-driver-template.git to your SmartServer as follow:

   > git clone https://github.com/izot/smartserver-driver-template.git
   You will see the following folders/files (not all files and folders are listed):
   	smartserver-driver-template
   	├── ...
   	├── example_xif.dtd
   	├── example_xif.xpl
   	├── Makefile
   	├── src
   	│   ├── common.h
   	│   ├── eti.cpp
   	│   ├── eti.h
   	│   ├── example.cpp
   	│   ├── example.h
   	│   ├── idl
   	│   │   ├── include
   	│   │   │   ├── cJSON.h
   	│   │   │   ├── csvin.h
   	│   │   │   ├── IdlCommon.h
   	│   │   │   └── libidl.h
   	│   │   └── lib
   	│   │       └── libidl.so
   	│   └── main.cpp
   	└── ...
   	5 directories, 25 files
   

4. Using an editor open the makefile and change the driver to a driver-specific information as needed: The driver identifier, driver name, description, manufacturer, license, version, filetype and file extension.

   NOTE: There is no support for CamelCase naming convention for the driver name.

5. Add any required additional components such as a protocol stack to the build script.
6. If necessary, change/add/complete the implementation of the required call-back functions. The example driver provides a minimum implementation required to do device creation, provisioning, deletion and reading/writing of datapoints.
7. Run make to build the new driver. The output of the build process will be a GLPO file with an installation script and driver image embedded in the file. The default output (per example driver) will be in build/release/example_driver.glpo files (not all files/folder are listed):

   	smartserver-driver-template
   	├── build
   	│   └── release
   	│       ├── example_driver.glpo
   	│       ├── ...
   	│       ├── glpo ...
   	│       │   └── ...
   	│       └── image ...
   	│           └── ...
   

8. Create a new driver-specific XIF file by copying and modifying the example_xif.xpl & example_xif.dtd (csv) files found in the smartserver-driver-template project below. For more info on XIF files, see https://enoceanwiki.atlassian.net/wiki/spaces/IEC/pages/2196199/Collecting+or+Creating+Device+Definitions

   Edit <your_driver>_xif.xpl
   	#filetype,<your_driver>_xif
   	#program_ID,<your_device_Program_ID>
   	#manufacturer,<your_manufacturer>
   	#description,<your_driver> xif
   
   Edit <your_driver>_xif.dtd
   	#filetype,dtd
   	"Device Type",Protocol,"Program ID","Default App","Default Sys","Auto App Load","Auto Sys Load","Graphics File",Default 
   	<your_driver>_device,<your_driver>,<your_device_Program_ID>,,,false,false,,false
   

9. Open the SmartServer CMS Devices widget and then click the Segment Controller tab.
10. Click the action button (vertical three dots next to the SmartServer).
11. Click the Update action.
12. Drag the newly created GLPO file to the Update Loader (Drop new update loader here) box.
13. Click the file button to save the driver package file to the SmartServer and then click the import button to load the driver to the SmartServer. The SmartServer will load and run the new driver as a service (cdriver:) under Smartserverctl.
14. Open the CMS Device Types widget.
15. Click the Import Device Type buitton and then drag the example_xif.xpl (_xif.ext) file to the Drop File Here box and click the Import File button to load the XIF file to the SmartServer.
16. Click the Back button and wait until the device type appears in the Device Types widget.
17. Open the SmartServer CMS Devices widget and then click the Edge Devices tab.
18. Click the "+" button to create a device with the following settings: name: _1, UID: 001, Integration Method: Manual assignment, Driver: , and select the one and only available device types and click the Save button. Wait until the newly created device appears in the Devices widget and is shown in blue (licensed, not purple - unlicensed) color.
19. Click the action menu (three vertical dots next to the newly created device) and then click the Provision action.
20. You can browse the datapoint values using the Datapoints widget. If you are using the attached example_xif.xpl XIF file, this example/ETI driver specific rules apply:
    • Device's unid (Name under CMS Devices Widget) is mapped to ETI's $dev_uid
    • Datapoint name designation RO=ReadOnly and RW-Read/Write access
    • In ETI, the Address column in XIF file designates the device reg index and mapped to ETI's $reg_index. (This mapping of Address field to device's reg index is only specific to ETI implementation. In other driver implementations, the Address field may be used differently such as to map a given device type to device's I/O port via the Address field.) ETI protocol syntax is as follow: eti/<your_driver>/[rd|wr|ev]/dev/$dev_uid/reg/$reg_id $data_value
    • Datapoints with the same Address field share the same reg index: one designated with RW and the other RO
    • COUNTER_RO and COUNTER_RW with Address 0 are mapped to physical address/reg 0
    • COUNTER_RO gets its value via the use of XIF Address/Reg & custom/unrecognized column "TestMultiplier". It basically takes the value written by COUNTER_RW in Reg 0 and multiply it by the value in "TestMultiplier".
    • Counter2_RO with Address 1 is mapped to physical address/reg 1. We can use the ETI protocol to update the value of Counter2 by publishing (using mosquitto_pub) to the following MQTT topic:

      mosquitto_pub -t eti/example/ev/dev/1003/reg/1 -m 30

    • Switch1_RO and Switch1_RW with Address 2 are mapped to physical address/reg 2
    • SwitchValue_RO and SwitchValue_RW with Address 3 are mapped to physical address/reg 3
    • SwitchState_RO and SwitchState_RW with Address 4 are mapped to physical address/reg 4
    • All datapoint read from the Datapoints Browser Widget results in the following rd MQTT topic publications: eti/<your_driver>/rd/dev/$dev_uid/reg/$reg_index

      NOTE: these read MQTT topic publication will not affect or cause datapoint value update

    • All datapoint write from the Datapoint Browser Widget results in the following wr MQTT topic publications: eti/<your_driver>/wr/dev/$dev_uid/reg/$reg_index <data payload>
    • All externally generated ETI MQTT ev topic publications as shown below will results in datapoint updates: eti/<your_driver>/ev/dev/$dev_uid/reg/$reg_index <data payload>
    • <data payload> will be in the JSON form like:
      • real number value (0, 1, 0.5, 95.5, etc.)
      • boolean (true, false)
      • objects ('{"state":value,"value":value}', '{"Name": "Apple","Price": 3.99,"Sizes":"Small"}', etc.)