Skip to content

Updating from IoTC v1.3 to IoTC v1.4

IOTC version 1.4 provides a significant improvement of the setup, management, and system functionalities to further enhance setup and operation of IOTC. To leverage these new features, IOTC v1.4 introduces an updated API referred to as API v2. IoTC v1.4 also includes a new device storing format together with additional services and environment variables. These changes did not allow to maintain backwards compatibility with IoTC v1.3. It is therefore required to follow below steps when updating from IoTC v1.3 to IoTC v1.4.

Generate system backup file

IoTC v1.4 introduces a new format for storing devices as shown below. It is therefore required to generate and modify an IoTC v1.3 system backup file to make it compatible with IoTC v1.4.

  1. Make a GET request to /api/v1/backup endpoint to generate a system backup
  2. Make the following modifications in the system backup file to make it compatible with IoTC v1.4.

Change the following variables throughout the backup file

  • APIVersion -> apiVersion

  • Connections -> devices

  • sourceEurid -> eurid

  • friendlyID -> friendlyid

Change isPTM to deviceType acording to below

  • isPTM: false -> deviceType: sensor

  • isPTM: true -> deviceType: switch

Update docker-compose.yml file

IoTC v1.4 requires additional services and environment variables to be added to the docker-compose.yml file. It is therefore required to update the docker-compose.yml file as described below before updating to IoTC v1.4. As reference for adding below services and environment variables it is recommended to download the docker-compose.yml file included in IoTC v1.4.

IoTC v1.4 introduced two new containers; rabbitmq and fluentd. The rabbitmq container is required for both local and Azure deployment whereas fluentd is only required for local deployment. The services must be added as shown below. 

fluentd: 
    user: root 
    image: enocean/iotconnector_fluentd:latest 
    volumes: 
        - /var/lib/docker/containers:/var/lib/docker/containers 
        - ./logs:/outputs/ 
    logging: 
        driver: local 

rabbitmq: 
    image: rabbitmq:3.10-management 
    ports: 
        - "15672:15672" 
        - "5672:5672"
In addition to these services environment variable below must be added to “engine”, “integration” and “ingress” services. 
environment: 
   ... 
   - RABBITMQ_HOST=rabbitmq 
   ...
Api service’s configuration changed with API v2 
api: 
    image: enocean/iotconnector_api:latest 
    ports: 
        - "1887" 
    restart: always 
    environment: 
        - REDIS_URL=redis://redis:6379/0 
        - LICENSE_KEY= # License is now required for API as well. 
        - DJANGO_SETTINGS_MODULE=eiotc_api.settings.dev 
    volumes: 
        - ./logs:/var/log/enocean/eiotc 
    depends_on: 
        - redis
Api url on engine configuration must be update to API v2 
engine:
    ...
    environment:
        ...
        - API_URL=http://api:1887/api/v2

Update to API v2

After updating to IoTC v1.4 it is required to align API integration with API v2 by going through each function in the API documentation.

Key changes in API v2 are:

  • Organization of all functions in three clearly defined groups (system, devices, gateways) for better structure and easier integration.

  • Extension of device functions with {deviceId} to allow addressing a specific device, for instance to request device information for one specific device.

  • Support of additional filter options for the GET /devices function to only show devices with a specific EEP, a specific deviceType or at a certain location.

  • Extension of gateway functions with {mac} to allow addressing a specific gateway, for instance to request device information for one specific gateway.

  • Support for backup functions has been moved into the system group

  • The new function GET/system/license has been added to easily verify if IoTC license is valid.

  • The new function GET/system/logs has been added to retrieve IoTC logs through the Swagger UI.