How to Get Started with EdgeX: A Step-by-Step Setup Guide

EdgeX Foundry is an open-source framework designed to simplify IoT edge computing by providing a vendor-neutral, modular platform for connecting devices, managing data, and deploying analytics at the edge. Built on microservices architecture, EdgeX enables developers to integrate sensors, actuators, and other IoT devices with cloud services or local applications without being locked into proprietary systems. Whether you’re building a smart building solution, industrial monitoring system, or home automation network, EdgeX provides the foundational services needed to collect, process, and act on device data in real-time. This guide walks you through setting up EdgeX from scratch, connecting your first sensor, and troubleshooting common issues along the way.

Key Takeaways

• EdgeX Foundry simplifies IoT device integration through its open-source, microservices-based architecture
• Docker-based installation can have EdgeX running in under 5 minutes on most systems
• Device profiles enable seamless communication between EdgeX and diverse sensors or actuators
• Troubleshooting resources from the EdgeX community help resolve setup and connection issues quickly

What is EdgeX and How Does It Work?

Overview of EdgeX

EdgeX Foundry is an open-source software framework hosted by the Linux Foundation that serves as a common foundation for IoT edge solutions. According to the Linux Foundation’s official project page, EdgeX was created to build a common open framework for IoT edge computing, fostering interoperability between devices, applications, and services. Think of EdgeX as a universal translator for IoT devices—it sits between your physical sensors (temperature monitors, cameras, motion detectors) and your applications (dashboards, analytics engines, cloud services), converting device-specific protocols into standardized data formats that any application can understand.

The framework operates through a collection of microservices, each handling specific tasks like device connectivity, data transformation, rule processing, or external system integration. This modular design means you can deploy only the services you need, keeping your edge deployment lightweight and efficient. For example, a simple temperature monitoring solution might use just the core data service, device service, and command service, while a complex industrial automation system could leverage additional services for analytics, security, and multi-site orchestration.

EdgeX follows a “south-north” data flow model: device services on the “southside” communicate with physical devices using protocols like Modbus, BACnet, or MQTT, while application services on the “northside” push processed data to cloud platforms, databases, or local applications. This architecture decouples device connectivity from application logic, allowing you to swap out devices or change cloud providers without rewriting your entire solution.

Benefits of Using EdgeX

EdgeX offers several compelling advantages for IoT projects. First, its vendor-neutral design prevents lock-in—you’re not tied to a specific hardware manufacturer, cloud provider, or protocol stack. This flexibility matters when you need to integrate legacy industrial equipment with modern IoT sensors or when business requirements force a cloud platform migration.

Second, the microservices architecture enables incremental adoption and scaling. You can start with a minimal deployment on a Raspberry Pi for proof-of-concept testing, then gradually add services as requirements expand. Each service runs in its own container, making it easy to update, replace, or scale individual components without disrupting the entire system.

Third, EdgeX accelerates development through reusable device services and application templates. Instead of writing low-level protocol handlers for every device type, you can leverage community-contributed device services for common protocols. The EdgeX Foundry Documentation provides extensive examples and reference implementations that reduce development time from months to weeks.

Fourth, the framework supports edge analytics and local decision-making, reducing cloud costs and latency. By processing data at the edge, you can filter noise, aggregate readings, and trigger immediate responses without round-tripping to the cloud. This capability is essential for time-sensitive applications like industrial safety systems or autonomous vehicle coordination.

What Are the System Requirements for Setting Up EdgeX?

Hardware Requirements

EdgeX is designed to run on resource-constrained edge devices, but requirements vary based on your deployment scale and enabled services. For development and testing purposes, a Raspberry Pi 4 with 4GB RAM provides a realistic edge environment. Production deployments typically require more robust hardware to handle continuous data streams and multiple device connections.

Network connectivity requirements depend on your device protocols and cloud integration needs. Local device communication typically uses minimal bandwidth (1-10 Mbps for most sensor networks), but cloud synchronization, video streams, or high-frequency industrial sensors may require 100 Mbps or faster connections. EdgeX supports both wired Ethernet and Wi-Fi connectivity, though wired connections provide more reliable performance for production deployments.

Software Prerequisites

EdgeX runs on Linux, Windows, and macOS, but Linux distributions like Ubuntu 20.04 LTS or newer provide the most straightforward setup experience. The framework uses Docker containers for deployment, so Docker Engine (version 20.10 or later) and Docker Compose (version 1.29 or later) are mandatory prerequisites. These tools handle service orchestration, networking, and dependency management automatically.

Before installing EdgeX, ensure your system meets these software requirements:

• Operating System: Ubuntu 20.04/22.04 LTS (recommended), Red Hat Enterprise Linux 8+, Windows 10/11 with WSL2, or macOS 11+
• Docker Engine: Version 20.10 or later with BuildKit support enabled
• Docker Compose: Version 1.29 or later (or Docker Compose V2 plugin)
• Network Access: Outbound internet access for pulling container images (initial setup only)
• User Permissions: Non-root user with Docker group membership or sudo access

For Raspberry Pi deployments, use Raspberry Pi OS (64-bit) for better performance and compatibility. The 32-bit version works but may encounter memory constraints with larger deployments. Windows users should enable WSL2 (Windows Subsystem for Linux 2) and install Docker Desktop, which provides a Linux kernel for container execution.

Additional tools enhance the development experience but aren’t strictly required: Git for cloning example repositories, Postman or curl for API testing, and a text editor like VS Code for configuration file editing. The EdgeX community recommends allocating at least 10GB of disk space for container images, logs, and data storage during initial setup.

How Do I Install EdgeX Step-by-Step?

Preparing Your Environment

Start by updating your system packages and installing Docker. On Ubuntu or Debian-based systems, open a terminal and run these commands:

bash

sudo apt update && sudo apt upgrade -y

sudo apt install -y docker.io docker-compose git curl

After installation completes, add your user account to the Docker group to run Docker commands without sudo:

bash

sudo usermod -aG docker $USER

newgrp docker

Verify Docker installation by checking the version:

bash

docker –version

docker-compose –version

You should see Docker version 20.10 or later and Docker Compose version 1.29 or later. If the versions are outdated, follow the official Docker installation guide for your operating system to install the latest release.

Next, create a dedicated directory for EdgeX files and navigate into it:

bash

mkdir ~/edgex-setup && cd ~/edgex-setup

This workspace will store Docker Compose files, device profiles, and configuration files. Keeping EdgeX files organized in a single directory simplifies management and troubleshooting.

Check your system’s available resources before proceeding:

bash

free -h # Check available RAM

df -h # Check available disk space

Ensure you have at least 2GB of free RAM and 8GB of free disk space. EdgeX container images total approximately 2-3GB, and running services consume an additional 500MB-1GB of RAM depending on enabled services.

Installing EdgeX: A Step-by-Step Setup Guide

The fastest way to get started with EdgeX is using the pre-built Docker Compose files from the official repository. According to the EdgeX Foundry official documentation, this setup guide approach provides the most reliable installation method. Download the latest stable release (as of 2026-06-09, version 3.0 “Minnesota” is current):

bash

curl -L https://github.com/edgexfoundry/edgex-compose/archive/refs/tags/v3.0.0.tar.gz -o edgex-compose.tar.gz

tar -xzf edgex-compose.tar.gz

cd edgex-compose-3.0.0

The extracted directory contains multiple Docker Compose files for different deployment scenarios. For a basic setup with core services, use the docker-compose.yml file:

bash

docker-compose -f docker-compose.yml up -d

The -d flag runs containers in detached mode (background). Docker will download container images on first run, which takes 5-10 minutes depending on your internet connection. You’ll see output like:

Creating network “edgex-compose_edgex-network” with driver “bridge”

Creating volume “edgex-compose_db-data” with default driver

Pulling core-consul (consul:1.15)…

Pulling core-metadata (edgexfoundry/core-metadata:3.0.0)…

…

Creating edgex-core-consul … done

Creating edgex-redis … done

Creating edgex-core-metadata … done

Creating edgex-core-data … done

Wait until all services show “done” status. The initial startup takes 2-3 minutes as services initialize databases, register with the configuration service, and establish inter-service connections.

For a more comprehensive deployment including device services and application services, use the extended compose file:

bash

docker-compose -f docker-compose.yml -f docker-compose-with-app-sample.yml up -d

This command layers the application sample services on top of the core services, demonstrating how to extend EdgeX with custom logic.

Verifying the Installation

Check that all EdgeX containers are running:

bash

docker ps

You should see approximately 10-15 containers with names like edgex-core-metadata, edgex-core-data, edgex-core-command, and edgex-redis. The STATUS column should show “Up” for all containers. If any container shows “Exited” or “Restarting”, check logs with:

bash

docker logs

Test the EdgeX REST API by querying the core metadata service:

bash

curl http://localhost:59881/api/v3/ping

A successful response returns JSON like:

json

{“apiVersion”:”v3″,”timestamp”:”2026-06-09T14:30:00Z”}

Access the EdgeX web UI by opening a browser and navigating to http://localhost:4000. The Consul UI provides a service health dashboard showing all registered EdgeX services. All services should display green checkmarks indicating healthy status.

Verify device service registration:

bash

curl http://localhost:59881/api/v3/deviceservice/all

This command returns a JSON array of registered device services. A fresh installation includes at least the virtual device service used for testing.

To test end-to-end functionality, trigger a reading from the virtual device:

bash

curl http://localhost:59882/api/v3/device/name/Random-Integer-Device/RandomValue

This command queries a simulated integer sensor. The response includes a randomly generated value, demonstrating that device services, core data, and metadata services are communicating correctly.

If all verification steps succeed, your EdgeX installation is ready for device integration. If any step fails, check the troubleshooting section below for common solutions.

How Do I Connect Sensors and Devices to EdgeX?

Understanding Device Profiles

Device profiles are JSON or YAML files that describe a device’s capabilities, communication protocol, and data format. Think of a device profile as a contract between EdgeX and your physical device—it tells EdgeX what commands the device accepts, what data it produces, and how to interpret that data.

A typical device profile contains three main sections:

1. Device Resources: Individual data points or controls (e.g., “temperature”, “humidity”, “LED_status”)
2. Device Commands: Groups of resources that can be read or written together
3. Protocol Properties: Protocol-specific settings like Modbus register addresses or MQTT topics

Here’s a simplified example of a temperature sensor profile:

yaml

name: “Temperature-Sensor-Profile”

manufacturer: “Generic”

model: “TMP-100”

labels: [“temperature”, “environmental”]

deviceResources:

– name: “Temperature”

description: “Current temperature in Celsius”

properties:

valueType: “Float32”

readWrite: “R”

units: “Celsius”

EdgeX includes pre-built profiles for common device types in the device service repositories. For custom devices, you’ll create a profile matching your device’s specifications. The profile is loaded into EdgeX when you add the device, enabling automatic data parsing and command translation.

Connecting Your First Sensor

Let’s walk through connecting a simulated REST sensor, which demonstrates the connection process without requiring physical hardware. First, ensure the device-rest service is running:

bash

docker ps | grep device-rest

If the device-rest service isn’t running, add it to your deployment:

bash

docker-compose -f docker-compose.yml -f docker-compose-device-rest.yml up -d

Create a device profile for your REST sensor. Save this content as rest-sensor-profile.json:

json

{

“name”: “REST-Sensor-Profile”,

“manufacturer”: “Tutorial”,

“model”: “REST-1”,

“labels”: [“rest”, “tutorial”],

“deviceResources”: [

{

“name”: “SensorValue”,

“description”: “Sensor reading value”,

“properties”: {

“valueType”: “Int32”,

“readWrite”: “R”

}

}

],

“deviceCommands”: [

{

“name”: “Values”,

“readWrite”: “R”,

“resourceOperations”: [

{

“deviceResource”: “SensorValue”

}

]

}

]

}

Upload the profile to EdgeX:

bash

curl -X POST http://localhost:59881/api/v3/deviceprofile \

-H “Content-Type: application/json” \

-d @rest-sensor-profile.json

Now register the actual device instance:

bash

curl -X POST http://localhost:59881/api/v3/device \

-H “Content-Type: application/json” \

-d ‘{

“name”: “REST-Sensor-01”,

“description”: “Tutorial REST sensor”,

“adminState”: “UNLOCKED”,

“operatingState”: “UP”,

“serviceName”: “device-rest”,

“profileName”: “REST-Sensor-Profile”,

“protocols”: {

“HTTP”: {

“Address”: “localhost”,

“Port”: “49999”,

“Path”: “/api/v1/sensor”

}

}

}’

This command creates a device named “REST-Sensor-01” that EdgeX will poll via HTTP at localhost:49999/api/v1/sensor. In a real deployment, you’d replace these values with your actual device’s network address and protocol parameters.

For physical devices using protocols like Modbus, MQTT, or BACnet, the process is similar but requires the appropriate device service. For example, connecting a Modbus temperature sensor involves:

1. Starting the device-modbus service
2. Creating a device profile with Modbus register mappings
3. Registering the device with its Modbus slave ID and network address

The EdgeX community provides example profiles for hundreds of commercial devices in the device service repositories, significantly reducing integration effort.

Testing the Connection

Verify your device is registered and visible to EdgeX:

bash

curl http://localhost:59881/api/v3/device/name/REST-Sensor-01

The response shows your device configuration including profile name, service association, and protocol settings. If the device doesn’t appear, check that the profile name in your device registration matches the uploaded profile name exactly—EdgeX is case-sensitive.

Query the device for a reading:

bash

curl http://localhost:59882/api/v3/device/name/REST-Sensor-01/Values

This command triggers the device service to contact your sensor and retrieve the “Values” command defined in the device profile. The response includes the reading value, timestamp, and metadata:

json

{

“apiVersion”: “v3”,

“statusCode”: 200,

“event”: {

“deviceName”: “REST-Sensor-01”,

“profileName”: “REST-Sensor-Profile”,

“readings”: [

{

“deviceName”: “REST-Sensor-01”,

“resourceName”: “SensorValue”,

“value”: “42”,

“valueType”: “Int32”,

“origin”: 1717945800000000000

}

]

}

}

Check that readings are being stored in the core data service:

bash

curl http://localhost:59880/api/v3/event/device/name/REST-Sensor-01?limit=10

This query retrieves the last 10 events from your sensor. If readings appear here, your device is successfully integrated with EdgeX’s data pipeline. Applications can now subscribe to these readings via the application services or query historical data via the core data API.

For continuous monitoring, configure auto-events in your device registration to poll the sensor at regular intervals:

json

“autoEvents”: [

{

“interval”: “30s”,

“onChange”: false,

“sourceName”: “Values”

}

]

This configuration tells EdgeX to read the “Values” command every 30 seconds automatically, eliminating the need for manual polling.

What Troubleshooting Steps Should I Follow If I Encounter Issues?

Common Installation Errors

Port Conflicts: If you see errors like “bind: address already in use”, another application is using EdgeX’s default ports. Identify the conflicting process:

bash

sudo lsof -i :59880 # Core data service port

Either stop the conflicting application or modify EdgeX port mappings in the Docker Compose file. To change ports, edit docker-compose.yml and update the port mappings under each service:

yaml

ports:

– “59880:59880” # Change left number to available port

Insufficient Memory: If containers repeatedly restart or show “OOMKilled” status, your system lacks sufficient RAM. Check Docker’s memory allocation:

bash

docker stats

If EdgeX services consume more than 80% of available memory, either add more RAM, reduce enabled services, or increase Docker’s memory limit in Docker Desktop settings (Windows/Mac) or daemon configuration (Linux).

Container Startup Failures: When a service fails to start, examine its logs for specific errors:

bash

docker logs edgex-core-metadata –tail 50

Common causes include:

• Missing dependencies (wait for database services to fully initialize)
• Configuration errors (check volume mounts and environment variables)
• Network issues (verify Docker network creation succeeded)

To restart all services cleanly:

bash

docker-compose down -v # Stop and remove volumes

docker-compose up -d # Fresh start

The -v flag removes persistent data, giving you a clean slate. Use this when configuration changes don’t take effect or when services are stuck in error states.

Debugging Connection Issues

Device Not Found: If API queries return “device not found”, verify the device name exactly matches the registered name:

bash

curl http://localhost:59881/api/v3/device/all | jq ‘.devices[].name’

This command lists all registered device names. EdgeX device names are case-sensitive and must match precisely in API calls.

No Readings Received: When devices register successfully but produce no readings, check:

1. Device service logs for connection errors:

bash

docker logs edgex-device-rest | grep ERROR

1. Network connectivity between EdgeX and the device (ping test, port scan)

1. Protocol configuration in device registration (IP address, port, Modbus slave ID, MQTT topic, etc.)

For REST devices, test the endpoint directly:

bash

curl http://your-device-ip:port/path

If this fails, the device isn’t reachable from the EdgeX container’s network. Check firewall rules and Docker network configuration.

Data Format Mismatches: If readings appear but contain unexpected values, the device profile’s valueType may not match the actual data format. Common mismatches:

• String data interpreted as Int32 (returns 0 or errors)
• Float values truncated to integers
• Binary data displayed as gibberish

Update the device profile’s valueType to match your device’s actual output format, then re-upload the profile.

Where to Get Help

The EdgeX community provides multiple support channels:

Official Documentation: The EdgeX Foundry Documentation covers architecture, API references, and deployment guides. Start here for authoritative information on features and configuration options.

Community Forums: The EdgeX mailing lists and Slack channels connect you with other users and core developers. Search existing threads before posting—many common questions have detailed answers from previous discussions.

GitHub Issues: For bugs or feature requests, open issues in the relevant repository (edgex-compose for deployment issues, specific device service repos for device connectivity problems). Include logs, configuration files, and reproduction steps to get faster responses.

Stack Overflow: Questions tagged with edgex-foundry reach a broader developer audience. Search existing questions first, as many setup and integration problems have documented solutions.

Video Tutorials: The EdgeX Foundry YouTube channel offers recorded workshops, architecture overviews, and hands-on demonstrations that complement written documentation.

When asking for help, always include:

• EdgeX version (check docker images | grep edgex)
• Operating system and Docker version
• Relevant log excerpts (use docker logs )
• Configuration files (sanitize sensitive information)
• Steps to reproduce the issue

Providing complete context helps community members diagnose issues quickly and suggest targeted solutions.

Frequently Asked Questions

Can I run EdgeX on a Raspberry Pi?

Yes, EdgeX runs well on Raspberry Pi 4 with 4GB or 8GB RAM. Use the 64-bit version of Raspberry Pi OS for better performance and compatibility with EdgeX container images. Install Docker using the official installation script, then follow the standard EdgeX installation steps. For Raspberry Pi 3 or devices with 2GB RAM, limit enabled services to core-only deployments to avoid memory constraints. The EdgeX community maintains ARM-specific container images that are automatically selected when you run docker-compose on ARM hardware.

What programming languages does EdgeX support?

EdgeX core services are written in Go, but the framework supports multiple languages for custom device services and application services. Official SDKs exist for Go, C, and Python, allowing you to write device services in your preferred language. Application services can be written in any language that supports REST APIs or message queues, including Java, Node.js, Rust, and C#. The Go SDK provides the most features and best performance, while the C SDK targets resource-constrained devices. Python SDK is ideal for rapid prototyping and integration with machine learning libraries.

How secure is EdgeX for IoT applications?

EdgeX provides several security features including API Gateway authentication, secret management via Vault, and service-to-service encryption. Security services are disabled by default in development deployments but should be enabled for production using the security-enabled Docker Compose files. EdgeX supports token-based authentication, TLS encryption for REST APIs, and encrypted message bus communication. For maximum security, deploy EdgeX behind a firewall, use strong passwords for all services, regularly update to the latest version to receive security patches, and enable audit logging to track API access. The EdgeX security working group continuously evaluates and improves the framework’s security posture.

Are there any costs associated with using EdgeX?

EdgeX Foundry is completely free and open-source under the Apache 2.0 license. There are no licensing fees, usage restrictions, or vendor lock-in. You can deploy EdgeX on any hardware, modify the source code, and use it in commercial products without royalty payments. However, you’re responsible for infrastructure costs (hardware, cloud services, network bandwidth) and support costs if you choose commercial support from vendors who offer EdgeX-based solutions. Many companies contribute to EdgeX development, ensuring the project remains vendor-neutral and community-driven.

Where can I find more advanced EdgeX tutorials?

The EdgeX Foundry Documentation includes advanced guides on custom device service development, application service pipelines, and multi-site deployments. The EdgeX GitHub organization hosts example repositories demonstrating integration patterns, protocol implementations, and reference architectures. Linux Foundation offers instructor-led training courses and self-paced learning paths covering EdgeX architecture, development, and deployment best practices. EdgeX DevDays events (recorded on YouTube) feature deep-dive sessions on advanced topics like machine learning at the edge, security hardening, and cloud integration patterns. Community members also publish blog posts and tutorials on Medium and personal sites—search for “EdgeX Foundry tutorial” to find recent content.

Risk Disclaimer: This article is for educational purposes only and does not constitute professional advice. EdgeX Foundry is an open-source project, and while the community strives for quality and reliability, deployments should be thoroughly tested before production use. Always review security best practices, conduct proper testing, and consider your specific requirements when implementing IoT solutions. The author and OneBullEx are not responsible for any issues arising from EdgeX deployment or use.

Keyword: How to Get Started with EdgeX: A Step-by-Step Setup Guide