meta-esper

Yocto layer for Esper Device Management integration.

Overview

This Yocto layer adds Esper device management capabilities to your Linux builds. Simply add this layer to your existing Yocto project, and your devices will automatically register with Esper on first boot using their unique serial numbers.

What this layer does:

• Downloads and installs Esper agent binaries during runtime
• Creates a one-time provisioning service that runs on first boot
• Automatically registers devices with Esper cloud
• Starts device management services (telemetry, remote commands)

What this layer does NOT do:

• Does not manage users or passwords (that's your responsibility)
• Does not create a complete OS image (it's meant to be added to YOUR image)
• Does not handle security policies (customers manage their own security)

Dependencies

• meta (OE-Core)
• meta-openembedded/meta-networking

Supported Yocto Releases

Compatible with Yocto releases: dunfell, kirkstone (LTS), langdale, mickledore, nanbield, scarthgap (LTS)

How It Works

1. Build Time: Layer adds provisioning script and systemd service to your image
2. First Boot: Provisioning service runs automatically
3. Runtime: Script downloads appropriate agent binaries for your architecture
4. Registration: Device registers with Esper cloud using its serial number
5. Activation: Agent services start and device becomes manageable
6. Cleanup: Provisioning service disables itself after successful completion

Network Failure Resilience

• Immediate retry: If provisioning fails, service retries after 30 seconds
• Periodic checks: Timer runs every 5 minutes to retry unprovisioned devices
• Automatic recovery: Once network connectivity is restored, device will provision automatically
• No manual intervention: System handles temporary network outages gracefully

Quick Integration

Step 1: Add the layer

cd your-yocto-build
bitbake-layers add-layer /path/to/meta-esper

Step 2: Add to your image

In your image recipe (e.g., your-custom-image.bb):

IMAGE_INSTALL += "esper-provisioner"

Step 3: Build

bitbake your-custom-image

That's it! Your devices will now automatically register with Esper on first boot.

What Happens

1. On first boot, the device reads its serial number
2. It contacts Esper cloud to register itself
3. Downloads configuration and starts agent services
4. Device appears in your Esper dashboard ready for management

Requirements

• Devices must be pre-registered in Esper dashboard with their serial numbers
• Internet connectivity required on first boot
• Serial number must be detectable (see Serial Number Sources below)

Architecture Support

The provisioner automatically detects your target architecture and downloads the appropriate binaries:

Architecture	Supported
amd64 (x86_64)	✅
arm64 (aarch64)	✅
arm (armv7l)	✅
x86 (i686)	✅

Serial Number Sources

The provisioner checks these locations in order:

• /sys/class/dmi/id/product_serial
• /sys/firmware/devicetree/base/serial-number
• /proc/cpuinfo (Serial field)
• /tmp/esper.id (custom override for testing)

Network Requirements

Devices need HTTPS access to:

• Esper cloud services for device registration
• Esper API endpoints for configuration
• MQTT services for device communication
• CDN for agent binary downloads

Troubleshooting

Build Issues

# Verify layer is recognized
bitbake-layers show-layers

# Test recipe builds
bitbake esper-provisioner

# Clean and rebuild if needed
bitbake -c cleanall esper-provisioner
bitbake esper-provisioner

Runtime Issues

Serial Number Detection

# Check available serial sources
cat /sys/class/dmi/id/product_serial
cat /proc/cpuinfo | grep Serial
cat /tmp/esper.id  # if using custom override

Network Connectivity

# Test connectivity
ping google.com
nslookup esper.io

Provisioning Failures

# Check provisioning logs
journalctl -u esper-provisioner
cat /var/log/esper-provisioning.log

# Manual provisioning for debugging
/usr/bin/esper-provisioner

# Check agent services after provisioning
systemctl status esper-cmse
systemctl status esper-telemetry

License

MIT License