The CIRCULOOS Platform utilizes FIWARE components, designed to be implemented on factory premises or on the cloud. It compatible with the NGSI-LD (Next Generation Service Interfaces) specifications. This platform setup serves as a template, equipped with minimal configurations to facilitate a smooth startup. Utilizing FIWARE generic enablers.
The main components of the circuloos IoT LD platform are:
-
- Role: Context Broker for NGSI-LD entity management
- Function: Real-time data storage and retrieval
-
- Role: NGSI-LD temporal retrieval API
- Function: Historical data queries and time-series analysis
- Documentation: OpenAPI Specifications
-
- Role: Identity and Access Management (IAM)
- Function: Single sign-on authentication and authorization
-
Kong as API Proxy
- Role: Policy Enforcement Point (PEP) proxy
- Function: API gateway for Orion-LD and Mintaka access control
- Docker and Docker Compose installed
- Linux environment (or WSL/VM for Windows users)
ONLY when you want to send data to the CIRCULOOS platform
- Valid partner credentials (delivered via secure email)
-
Credential Setup
- Locate
partner_variables.txtfrom your integration package - Configure required parameters:
PARTNER_USERNAME: Assigned partner usernamePARTNER_PASSWORD: Assigned partner password- Centennial value: Update as specified in credentials
- Locate
-
Missing Credentials
- Contact:
konstantinos.gombakis@eurodyn.com - Include organization name and use case in request
- Contact:
All platform interaction commands are available in commands_URL directory.
For interacting with YOUR local the same commands are available in commands directory.
Postman Collection: ED CIRCULOOS Platform.postman_collection.json
To provide/send data to the CIRCULOOS data platform you have 2 available methods:
Send valid NGSI-LD JSON directly to Orion-LD with proper authentication tokens from Keycloak.
Configure local Orion-LD to forward selected data to CIRCULOOS Orion-LD automatically.
- Documentation: Readme_federation.md
Tenant Configuration: Select a unique NGSILD-Tenant identifier to ensure data isolation between partner organizations.
Required Tools:
docker-composecurlbashjq(for JSON formatting)
Installation References:
Option 1: Virtual Machine
- Install VirtualBox
- Deploy latest Ubuntu LTS
Option 2: WSL (Windows Subsystem for Linux)
wsl --install --distribution UbuntuThen install Docker
-
Clone Repository
git clone [repository-url] cd circuloos-platform -
Start Platform
./service.sh start
Initial startup downloads Docker images (~10 minutes depending on connection)
-
Verify Services Open new terminal and proceed to testing commands
Main Configuration: docker-compose.yml
Additional Service Files:
temporal.yml: Mintaka and TimescaleDB serviceskeycloak.yml: Keycloak and Kong servicescirculoos_custom_apps.yml: CSV transformation and leather board outline tools
Navigate to commands directory:
cd commandsOrion-LD Status:
./getOrionVersion.sh: Direct Orion-LD version check./getOrionVersionViaKong.sh: Orion-LD via Kong proxy (production method)
Mintaka Status:
./getMintakaVersion.sh: Direct Mintaka version check./getMintakaVersionViaKong.sh: Mintaka via Kong proxy (production method)
Data Ingestion: A simple Indoor Enviromental Quality sensor measurements have been encoding used NGSI-LD JSON (demo_1_ieq-001_15min.json). With the following commands you can send/POST the measurements to the Orion CB.
./addDataOrion.sh circuloos_demo ../ieq_sensor/demo_1_ieq-001.json: Direct data upload./addDataOrionViaKong.sh circuloos_demo ../ieq_sensor/demo_1_ieq-001_15min.json: Production method via Kong./addDataOrionViaKong.sh circuloos_demo ../ieq_sensor/demo_1_ieq-001_30min.json: Additional test data
Current Data Retrieval:
./getDataOrionSensor.sh circuloos_demo urn:ngsi-ld:circuloos:demo_1:ieq-001: Latest measurement retrieval./getDataOrionSensorViaKong.sh circuloos_demo urn:ngsi-ld:circuloos:demo_1:ieq-001: Production method via Kong
Historical Data Retrieval:
./getDataMintaka.sh circuloos_demo urn:ngsi-ld:circuloos:demo_1:ieq-001: Historical data from Mintaka./getDataMintakaViaKong.sh circuloos_demo urn:ngsi-ld:circuloos:demo_1:ieq-001: Production method via Kong
By default the following tools are disabled. To enable them uncomment the L13 of service.sh
#CIRCULOOS_YML=" -f circuloos_custom_apps.yml" -> CIRCULOOS_YML=" -f circuloos_custom_apps.yml"
and stop (./service.sh stop), build the containers - will take some time (./service.sh build) and start again the applications (./service.sh start).
Purpose: Transform CSV data into NGSI-LD entities and upload to Orion-LD
A custom agent have been created to transform a CSV to NGSI-LD entities and send/POST them to the Orion-LD.
- Create the csv file with the data that you want to add to the Orion-LD. IMPORTANT the first 2 columns MUST BE id,type. See csv_NGSILD_Agent/leatherProducts.csv for a csv file with 2 entities. To add timestamp for the data add a column "observedat" with the date time into a ISO8601 format ("2024-01-31T12:03:02Z"), otherwise the timestamp will be set to current date/time.
- Go to http://localhost:5000, click on "Browse..." to select a csv file. Next click "Upload".
- Click "Generate NGSI-LD entities". A JSON representation of the NGSI-LD of the csv entities will appear.
- Click "Post NGSI-LD entities to Orion-LD". The created NGSI-LD JSON will be send to the Orion-LD. A message with the IDs of the send to the Orion-LD will appear.
- See the data send to the Orion-LD
./getDataOrionSensors.sh circuloos_demo leather
In order to send the data to the official CIRCULOOS platform the file 'csv_NGSILD_Agent/circuloos-csv-ngsild-agent.yml' needs to be updated with the partner's username and passowrd.
- Stop any running CIRCULOOS dockers, by running
./service.sh stop - Update csv_NGSILD_Agent/circuloos-csv-ngsild-agent.yml
- Run the
docker compose -f circuloos-csv-ngsild-agent.yml upinside folder csv_NGSILD_Agent - Follow previous instructions
Purpose: Calculate coordinates from irregular leather board images using ArUco markers
A tool to calculate and transform the image of an irregular leather board to coordinates with the help of Aruco marker along side with the necessary metadata.
Print the aruco markers from the pdf and measure them. Then, update the configuration of the docker that you run (local testing or CIRCULOOS platform) NUMBER_ARUCO_MARKERS with the number of markers that you are using and SIZE_IN_METERS_ARUCO_MARKERS the size of the printed markers in meters.
For the demo 2 aruco markers with dimensions of 0.045m (4.5cm) is used.
The leather/fabric MUST be photographed with a white background. Moreover there should be as flat as possible with no visible shadows. The aruco markers can be glued or taped on the surface and a piece of glass can be put on top of the leather/fabric.
IMPORTANT when you download/update (via git pull) rebuild the local docker images !!! ./service.sh build or docker compose -f leather_board_outline/leather-board-outline-irregular.yml build
- Ensure that the platform for local development is down. Run
./service.sh stopon the main directory - Edit the
leather_board_outline/leather-board-outline-irregular.ymlwith the credentials that you have received. - Run the docker compose:
docker compose -f leather_board_outline/leather-board-outline-irregular.yml up - Follow the instruction got as the local one (with ./service.sh start)
- Go to http://localhost:8501
- Upload the image with the aruco markers and the leather board. For demo you can use the
/leather_board_outline/imagesfabric_1_no_ruller.jpg - Examine the generated outline
- Fill all the necessary metadata/NGSI-LD properties required for the leather board. The id have been filled with a random name, please update it BUT it needs to start with urn:ngsi-ld:leather:. If the color in not present on the list please use the option
other colourand a color selector will apera to select the required colour - Click
Generate NGSI-LD JSONbutton. If any of the required data is not filled a error message will appear - optional Click
Show NGSI-LD JSONbutton to see the generated NGSI-LD JSON with all the data - optional Click
Download NGSI-LD JSONbutton to see the generated NGSI-LD JSON with all the data - optional Click
Check connectivity with CIRCULOOS platformto check the connectivity with the CIRCULOOS platform. - Click
Send data to CIRCOLOOS platformbutton to send the NGSI-LD JSON to the local or CIRCULOOS platform. A popup message will inform you about the status of the operation
A tool to calculate and transform to coordinates the remaining part of a rectangle leather board/sheet for recycling. Need to know the dimensions of the rectangle leather board
- Go to the http://localhost:8503
- Set the outside dimensions (width, height) of the leather board.
- Upload the image of the leather board. The removed/cut peaces MUST be with white colour. See folder leather_board_outline/full_image_demonstrating for examples.
- The image, remaining, removed material will appear and statistics will be printed.
- Click "Download Coordinates of remaining board" to download the coordinates. You can use them on with the previous tool to upload the data to the Orion-LD. See leather_outline.csv as example.
Docker Image Updates: After repository updates, rebuild local images:
./service.sh build
# or
docker compose -f [specific-compose-file].yml buildService Connectivity: Verify all services are running and accessible before proceeding with data operations.
Data Upload Failures:
- Verify credentials configuration
- Check tenant naming conventions
- Ensure NGSI-LD JSON validity
A dedicated debugging script is available to help diagnose platform issues:
cd commands
./debug-platform.shThis script provides comprehensive system health checks including service status, connectivity tests, and configuration validation.
Check all running containers:
docker psCheck all containers (including stopped):
docker ps -aInspect specific container:
docker inspect [container-name]Test Orion-LD direct access:
curl -X GET http://localhost:1026/ngsi-ld/ex/v1/versionTest Orion-LD via Kong:
cd commands
./getTokenForOrion.sh
# Then use the token to test authenticated access
./getOrionVersionViaKong.shVerify Keycloak is running:
curl -X GET http://localhost:8082/realms/fiware-server/.well-known/openid-configurationTest token generation:
cd commands
./getTokenForOrion.sh
# Check if a valid token is returnedDebug token issues:
- Check Keycloak logs for authentication errors
- Ensure Kong is properly configured to communicate with Keycloak
Check TimescaleDB data directory:
docker volume inspect circuloos-data-platform_timescaledb-dataCheck volume mounts:
docker inspect [container-name] | jq '.[0].Mounts'Check if ports are already in use:
# Check common ports used by the platform
sudo netstat -tulpn | grep -E ':(1026|8082|8000|5432|5000|8501|8503)'Or using lsof:
sudo lsof -i :1026 # Orion-LD
sudo lsof -i :8082 # Mintaka/Keycloak
sudo lsof -i :8000 # KongMonitor container resource usage:
docker statsCheck container resource limits:
docker inspect [container-name] | jq '.[0].HostConfig.Memory'Validate JSON syntax:
cat your-data.json | jq .Test with minimal entity:
{
"id": "urn:ngsi-ld:test:001",
"type": "TestEntity",
"@context": ["https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"]
}Complete platform reset:
./service.sh stop
docker system prune -a --volumes # WARNING: Removes all unused containers, networks, images, and volumes
./service.sh startReset specific service:
docker compose restart [service-name]Platform debug logs can be found in:
- Container logs:
docker logs [container-name] - Debug logs directory: debug-logs/
- Application-specific logs within containers
"Connection refused" errors:
- Verify service is running:
docker ps - Check port mappings are correct
- Ensure no firewall blocking
"Unauthorized" or "403 Forbidden":
- Verify authentication token is valid
- Check Keycloak realm and client configuration
- Ensure user has proper permissions
"Entity already exists" errors:
- Use PATCH instead of POST to update
- Or delete existing entity first
- Check for duplicate IDs
TimescaleDB connection errors:
- Verify TimescaleDB container is running
- Check database credentials
- Ensure Mintaka can reach TimescaleDB
Technical Contact: konstantinos.gombakis@eurodyn.com
Support Request Information:
- Organization name
- Tenant identifier (if applicable)
- Error messages and logs
- Reproduction steps
Copyright © 2023-2026 European Dynamics Luxembourg S.A.
Licensed under the EUPL, Version 1.2. You may not use this work except in compliance with the License. You may obtain a copy of the License at https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.



