/
(Optional) Add a Remote EnOcean Interface

(Optional) Add a Remote EnOcean Interface

Remote EnOcean Interface with IoTC is supported with SmartServer 4.3 Update 1 and higher.
Remote EnOcean Interface with SmartStudio is supported with SmartServer 4.5 Update 1 and higher.
SmartConnect is available with SmartServer 4.2 and higher. 

For SmartServer IoT 4.5 and prior, see (Optional) Add a Remote EnOcean Interface (Beta) for SmartServer IoT (Release 4.5 and Prior).

For SmartConnect 4.5 and prior, see (Optional) Add a Remote EnOcean Interface (Beta) for SmartConnect (Release 4.5 and Prior).

You can use the SmartServer to integrate and manage EnOcean devices in remote mode with EnOcean IoT Connector (IoTC) (available with SmartServer 4.3 Update 1 and higher) or EnOcean SmartStudio Platform (available with SmartServer 4.5 Update 1 and higher).

See (Optional) Add an EnOcean Interface for more information about adding EnOcean interfaces.

This section describes how to configure and use the SmartServer remote mode with IoTC or SmartStudio and consists of the following:

Setting up Remote EnOcean Interface

To set up and use SmartServer remote EnOcean interface with IoTC or SmartStudio, follow these steps:

  1. Enable remote mode with IoTC/SmartStudio as described in the Enabling Remote Mode section on this page.

  2. Optionally, add an EnOcean USB network interface as described in the (Optional) Adding an EnOcean USB Network Interface section on this page.

  3. Optionally, configure Local Antenna Tunnel to securely push data to IoTC/SmartStudio as described in the (Optional) Configuring Local Antenna Tunnel section on this page.
     

  4. Download and modify (as needed), or create an EnOcean device interface (XIF) and device type definition as described in the Downloading and Creating EnOcean Device Interface (XIF) and Device Type Definitions section on this page.

  5. Define datapoint properties for any datapoints to be monitored or logged as described in Setting Datapoint Properties.

  6. Create or discover devices as described in Site Provisioning. See the step-by-step example in the Adding Remote EnOcean Devices section on this page.

  7. Optionally, provide a BACnet interface for your EnOcean device; see Setting up the BACnet Server.  This application enables you to use a BACnet workstation with your EnOcean device.

Enabling Remote Mode

The sections that follow describe how to configure remote mode with IoTC or SmartStudio.

Enabling Remote Mode with IoTC

The procedure in this section describes how to enable remote mode with IoTC using the EnOcean Configuration page. This procedure sets the MQTT and IoTC parameters. The MQTT parameters define the connection information and authentication credentials to the MQTT broker of IoTC. The IoTC parameters define the connection information and authentication credentials to the REST API of IoTC. Depending on your environment, the MQTT and IoTC credentials (username and password) may be the same or different.

If your MQTT and IoTC instance credentials are the same, then follow the procedure below to enable remote mode with IoTC using the EnOcean Configuration page. If your MQTT and IoTC instance credentials are different, or if your IoTC instance is not using security on the MQTT side, then see Remote Mode with EnOcean IoTC Needs To Be Manually Started for SmartServer IoT or Remote Mode with EnOcean IoTC Needs To Be Manually Started for SmartConnect.

  1. For SmartServer IoT, log into the Configuration page as described in Accessing the SmartServer IoT Configuration Page. For SmartConnect, log into the Configuration page as described in Accessing the SmartConnect Configuration Page and click the SmartServer IoT tab (left side) as needed.

    The System tab appears.

    image-20250606-015029.png
    SmartServer IoT System Tab

     

    image-20250327-230611.png
    SmartConnect System Tab

     

  2. Click the EnOcean tab. The EnOcean tab appears. The EnOcean driver is enabled by default for SmartServer IoT and disabled by default for SmartConnect.

    image-20250606-014915.png
    SmartServer IoT EnOcean Tab

     

    image-20250327-231039.png
    SmartConnect EnOcean Tab

     

  3. Set the EnOcean driver to Enabled as needed and select the Remote with IoTC mode option.

    image-20250609-232333.png
    SmartServer IoT EnOcean Tab

    image-20250402-190207.png
    SmartConnect EnOcean Tab

     

  4. Configure the remote interface MQTT and IoTC (API) settings including the following:

    1. IP address or hostname – set the IoTC instance IP address or hostname.

    2. MQTT port – sets the MQTT port.

    3. Username – sets the MQTT and IoTC username credentials (i.e., MQTT_USERNAME or BASIC_AUTH_USERNAME in IoTC).

    4. Password – sets the MQTT and IoTC password credentials (i.e., MQTT_PASSWORD or BASIC_AUTH_PASSWORD in IoTC).

    5. Keep alive – set the keep alive interval for MQTT connections.

  5. Click Update.

    Remote EnOcean interface with IoTC is now enabled on your SmartServer.

  6. If you have more than one SmartServer connecting to a given IoTC instance, then verify that every client that connects to the same IoTC instance has a unique clientid. The clientid parameter provides a way to identify your specific connection and is assigned using the format <user>-smartserver-<segment ID> when remote mode is enabled. This parameter can be verified/modified in the iotcid.conf file as described in Remote Mode with EnOcean IoTC Needs To Be Manually Started for SmartServer IoT or Remote Mode with EnOcean IoTC Needs To Be Manually Started for SmartConnect.

Enabling Remote Mode with SmartStudio

To enable remote mode with SmartStudio, perform the following steps:

  1. For SmartServer IoT, log into the Configuration page as described in Accessing the SmartServer IoT Configuration Page. For SmartConnect, log into the Configuration page as described in Accessing the SmartConnect Configuration Page and click the SmartServer IoT tab (left side) as needed.

    The System tab appears.

    image-20250606-015029.png
    SmartServer IoT System Tab

     

    image-20250327-230611.png
    SmartConnect System Tab

     

  2. Click the EnOcean tab. The EnOcean tab appears. The EnOcean driver is enabled by default for SmartServer IoT and disabled by default for SmartConnect.

    image-20250606-014915.png
    SmartServer IoT EnOcean Tab

     

    image-20250327-231039.png
    SmartConnect EnOcean Tab

  3. Set the EnOcean driver to Enabled as needed and select the Remote with SmartStudio mode option.

    image-20250609-232226.png
    SmartServer IoT EnOcean Tab

    image-20250326-182443.png
    SmartConnect EnOcean Tab

     

  4. Enter the SmartStudio credentials in the appropriate fields including the following:

    1. SmartStudio Username – sets the SmartStudio login username credentials.

    2. SmartStudio Password – sets the SmartStudio login password credentials.

    3. MQTT Password – sets the authentication password of the SmartStudio MQTT broker. This value can be found in SmartStudio. Go to SmartStudio → Integration → Applications: SmartServer → MQTT Password field.

    4. Keep Alive – keep alive interval for MQTT connections.

       

  5. Click Update.

Remote mode with SmartStudio is now enabled on your SmartServer.

(Optional) Adding an EnOcean USB Network Interface

You can optionally attach an EnOcean USB network interface (shown below) by plugging it into an available USB drive on your SmartServer IoT to add support for communicating with your local EnOcean devices.

(Optional) Configuring Local Antenna Tunnel

If a local EnOcean radio is used, then you can optionally configure the SmartServer to securely push data to IoTC/SmartStudio using the Local Antenna Tunnel settings on the EnOcean Configuration page. Follow the steps below to configure Local Antenna Tunnel settings.

  1. Verify that an EnOcean USB network interface is plugged into a USB drive on your SmartServer.

  2. For SmartServer IoT, log into the Configuration page as described in Accessing the SmartServer IoT Configuration Page. For SmartConnect, log into the Configuration page as described in Accessing the SmartConnect Configuration Page. Click the SmartServer IoT tab (left side) as needed.

    The System tab appears.

    image-20250606-015029.png
    SmartServer IoT System Tab

     

    image-20250327-230611.png
    SmartConnect System Tab

     

  3. Click the EnOcean tab. The EnOcean tab appears.

    image-20250609-232333.png
    SmartServer IoT EnOcean Tab

     

    image-20250402-190207.png
    SmartConnect EnOcean Tab

     

  4. If Local Antenna Tunnel is not installed, then click Install Local Antenna Tunnel.

    If Local Antenna Tunnel is not installed and you are running SmartServer 4.5 Update 1, then first follow the procedure in the Starting Local Antenna Tunnel section and then click Install Local Antenna Tunnel.

    image-20250609-234128.png
    SmartServer IoT EnOcean Tab


    The Local Antenna Tunnel settings appear.

    image-20250609-234406.png
    SmartServer IoT EnOcean Tab

     

  5. Set the Local Antenna Tunnel  option to Enabled and configure the settings as follows:

    image-20250610-010142.png
    SmartServer IoT EnOcean Tab

     

    image-20250327-154015.png
    SmartConnect EnOcean Tab

     

    1. Auth URL – sets the EnOcean IoTC/SmartStudio cloud URL as supplied by your IoTC/SmartStudio provider.

      1. For IoTC, use the format https://<Fully Qualified Domain Name of the IoTC instance>:8080/auth/cisco.

      2. For SmartStudio, this value can be found in the SmartStudio Authentication URL field. Go to SmartStudio → Integration → Gateways: SmartServer Local→ Authentication URL field.

    2. Host DEV – use the pulldown menu to define the SmartServer USB where the EnOcean radio is connected. To determine which port is being used, enter the following command from a SmartServer IoT or SmartConnect console connection:

      sudo ls -l /dev/serial/by-id/ | grep usb-EnOcean_GmbH

      A response similar to the one shown below is returned, where the port in the example below is ttyUSB0:

      lrwxrwxrwx 1 root root 13 Mar 17 14:48 usb-EnOcean_GmbH_USB_500U_DA_EO6TD13G-if00-port0 -> ../../ttyUSB0

    3. Username – sets the EnOcean IoTC/SmartStudio ingress username credentials.

      1. For IoTC, this value is the ingress username (IOT_GATEWAY_USERNAME). See EnOcean IoT Connector Documentation for IoTC environment variable information.

      2. For SmartStudio, this value can be found in the SmartStudio Username field. Go to SmartStudio → Integration → Gateways: SmartServer Local → Username field.

    4. Password – sets the EnOcean IoTC/SmartStudio ingress password credentials.

      1. For IoTC, this value is the ingress password (IOT_GATEWAY_PASSWORD). See EnOcean IoT Connector Documentation for IoTC environment variable information.

      2. For SmartStudio, this value can be found in the SmartStudio “Token / Password” field. Go to SmartStudio → Integration → Gateways: SmartServer Local → “Token / Password” field.

    5. Client ID – sets a user-defined client identifier. If you have more than one tunnel within the same IoTC/SmartStudio instance, then specify a unique Client ID for each tunnel. Every client that connects to the same IoTC/SmartStudio instance must have a unique Client ID.

    6. Identifier – sets your SmartServer MAC ID without the colons (e.g., 00d0710d29b5). You can find your SmartServer MAC ID on the SmartServer System Configuration page. See Viewing System Information.

    7. Skip TLS and hostname verification – enable this option to skip TLS and hostname verification.

    8. Certification authority file (PEM) – if you are using Privacy Enhanced Mail (PEM) certification authority files or CRT files, then upload these files using the Drop the file to import, or browse feature. You can skip TLS and hostname verification by enabling the above optio

  6. Click Update to save the Local Antenna Tunnel configuration.

Local Antenna Tunnel is now started on your SmartServer.

Downloading and Creating EnOcean Device Interface (XIF) and Device Type Definitions

You can download and optionally modify EnOcean device interface (XIF) and device type definitions. You can also manually create custom EnOcean XIF and device type definitions. To download and modify EnOcean device interface (XIF) and device type definitions, follow these steps:

  1. If you are downloading EnOcean XIF definitions, then download the EnOcean device type package (.dtp) files from the SmartServer GitHub Repository. You can optionally modify the EnOcean XIF files to hide selected datapoints.

  2. If you are creating a custom EnOcean XIF definition (.iotc), then see (Optional) Creating a Remote EnOcean Device Interface (XIF) Definition.

  3. If you are creating a custom EnOcean device type definition (.dtd), then see Defining Device Types.

  4. If you were previously configured for EnOcean local mode, then open the SmartServer IoT CMS or SmartConnect CMS and remove local EnOcean interface device types (.eno) from the Device Types widget. See Defining Device Types.

  5. Import the EnOcean device interface (XIF) and device type definitions using the Import / Export button () on the SmartServer app bar.


    Once the EnOcean XIF and device type definitions are loaded, the device type definitions will appear in the Device Types widget.

     

  6. Define datapoint properties for any datapoints to be monitored or logged as described in Setting Datapoint Properties.

Adding Remote EnOcean Devices 

Once you have enabled remote mode and imported EnOcean device types, you can manually add EnOcean devices and/or discover EnOcean devices. To add EnOcean devices using remote mode, perform the following steps.

  1. Open the SmartServer IoT CMS or SmartConnect CMS.

  2. Open the Devices widget.

     

  3. If you were previously configured for EnOcean interface local mode, then remove the EnOcean devices from the Devices widget. See Discovering, Defining, or Importing Devices.

  4. If you are manually adding EnOcean devices, then set the Create Edge Devices fields as shown in the example below. See Discovering, Defining, or Importing Devices. 

    • Name – enter a name for the device

    • UID – enter the ID that is printed on the back of the device (e.g., 04208BA6). Use the 8 least significant bytes of the ID.
       

      image-20250214-175650.png

    • Integration method – select Manual assignment 

    • Driver – select iotc

    • Device Type – select the device type (e.g., STM550-V1-1)

      The devices are added and provisioned.

  5. If you are discovering EnOcean devices using remote mode with IoTC/SmartStudio, then click the Discover button () on the Devices widget. See Discovering, Defining, or Importing Devices for more information on how to discover devices.


    The discovered remote EnOcean devices appear in the Devices widget and are automatically provisioned.

    image-20250214-190852.png

     

    If you discover EnOcean devices using remote mode with IoTC, then you will see a multisensor device with the UID 04211939; this entry is a health check device and not a real device in IoTC.

     

  6. If discovery continues to run, click the Stop button (image-20250214-191115.png) as described in Discovering, Defining, or Importing Devices.