Edge Device Setup Guide
Contents
- Overview
- Virtual Edge Setup (Recommended)
- Physical Edge Device Setup
- Network Requirements
- Edge-to-Machine Protocol Ports
- Verification
- Data Retention and Connectivity
- Troubleshooting Common Issues
- Getting Help
- Next Steps
Overview
Edge devices play a critical role in getting data from your equipment to the MachineMetrics Cloud. These hardware components are located at the "edge" of the network, serving as gateways that bridge the physical and digital worlds between your machines and the cloud.
What is an Edge Device and Why You Need One
MachineMetrics Edge Devices connect to equipment on the machine network, gather and normalize data, and securely transmit it to the MachineMetrics Cloud. The Edge also reaches out to the cloud for updates and configuration changes. All communication is edge-initiated outbound. There are no inbound firewall requirements.
Network Requirements: See the Network Requirements Guide for detailed firewall rules, required ports, and domains.
MachineMetrics Physical Edge Device - An Intel NUC-based appliance that comes pre-loaded with MachineMetrics software. The compact edge device connects to your machine network and the internet, serving as the gateway between your shop floor equipment and the MachineMetrics Cloud.
Physical vs Virtual: When to Use Each
Virtual Edge Devices (Recommended) are software-based versions that run on virtualization platforms like VMWare or Hyper-V. They are ideal for:
- Quick deployment and testing
- Environments with existing virtualization infrastructure
- Easy scalability across multiple sites
- Most production environments
Physical Edge Devices are hardware appliances (typically Intel NUC-based) that come pre-loaded with MachineMetrics software. They are ideal for:
- Locations requiring multiple network interfaces
- Environments where dedicated hardware is preferred
- Specific use cases where physical hardware is required
Virtual Edge Setup
Virtual Edges are software-based versions of their physical counterparts. They simulate the functionalities of physical edge devices, allowing for quick deployment, easy scalability, and convenient testing.
System Requirements
Before provisioning your Virtual Edge, ensure you have the following:
- An account on the MachineMetrics platform with either Manager or Executive level permissions
- You have the capacity on your virtualization environment to provision a device with:
- x86 processor
- 4 Cores
- At least 6GB of RAM
- 64GB of storage
- A reliable internet connection
- A computer for downloading the image and connecting to the virtualization environment to deploy it
Supported Virtualization Environments
Our platform supports several popular virtualization environments. A download link is provided for each environment along with detailed steps for deploying the image.
IMPORTANT: The .ova file will expire. If your team is using a saved file and it is stuck in a loading screen, please download a new file.
VMWare
VMWare can be used to provision the MachineMetrics Virtual Edge software in production environments.
Minimum Version: 6.7+
Hyper-V
Hyper-V can be used to provision the MachineMetrics Virtual Edge software in production environments.
Minimum Version: Any version running on a currently supported Windows version
Configuration and Activation
After deploying the Virtual Edge image in your virtualization environment:
- Start the virtual machine
- Follow the same activation steps as physical devices (see Activation Steps below)
- The on-screen setup wizard will guide you through network configuration and device activation
Physical Edge Device Setup
Hardware Requirements
Before setting up your physical edge device, ensure you have the following:
- A MachineMetrics Edge device
- A reliable internet connection
- A computer for downloading the image (if reflashing is needed)
- A thumb drive with a minimum of 16GB of storage (if reflashing is needed)
- A keyboard, monitor, and mouse connected to the edge device
- An account on the MachineMetrics platform with either Manager or Executive level permissions
Option A: Using a Pre-Configured MachineMetrics Edge Device
If you purchased an edge device directly from MachineMetrics, it comes with our software already installed. Simply proceed to the Activation Steps section below.
Option B: Reflashing a MachineMetrics Edge Device
If you need to restore or repair a MachineMetrics Edge device, follow these steps:
Note: We recommend purchasing pre-configured MachineMetrics Edge devices. If you need to reflash a device, contact support for guidance.
1. Download and Prepare Your Thumb Drive
- Download the latest image:
- Commercial Client Users: Download Here
- GovCloud Client Users: Download Here
- Download and install balenaEtcher on your computer
- Run balenaEtcher and click on "Flash from file". Locate and select the downloaded image from step 1
- Insert your thumb drive into the computer. In balenaEtcher, select "Select target" and choose your thumb drive
- Click on "Flash!" to start the flashing process
- balenaEtcher will verify that the flashing process was successful. If this fails, repeat the process starting at step 3
Note: While you can use the same thumb drive for multiple edge devices, this image expires and is replaced every week. Always download the latest image before starting the provisioning process.
2. Flash the Edge Device
- Safely remove the thumb drive from your computer and insert it into the edge device
- Turn on the edge device and boot from the thumb drive. You may have to make adjustments in the BIOS to select the boot volume. This process may vary depending on the device; consult your device's manual if necessary
- Once the device has finished booting from the thumb drive, it will automatically start the flashing process. At this stage, the screen will only display a flashing cursor in the upper left-hand corner. This will remain for a few minutes while the device is being flashed
- When the flashing is complete, the monitor will indicate there is no device connected. If you are using a MachineMetrics Edge device, the light on the power button will turn amber at this point
- After the flashing process is complete, unplug the thumb drive from the edge device and power it on
Activation Steps
Once your edge device is powered on with peripherals connected, follow these steps:
Step 1: Welcome Screen
Once your edge device is powered on and your peripherals are connected, a logo will appear for 10-15 seconds and you'll then be presented with a welcome screen. Click "Let's get started!" to proceed.
Step 2: Establish an Internet Connection
The next step is to get your edge device connected to the internet. You'll be presented with two connection options: WiFi or Ethernet.
WiFi Connection:
- Select 'WiFi' as your preferred connection method
- You will then be prompted to choose the WiFi network from a list
- Select your preferred network and type in the password
Ethernet Connection:
- If you prefer a wired connection, select 'Ethernet'
- You'll be prompted to select the network interface. If one of the Ethernet ports is plugged in, you'll see that noted in the list as 'Connected'
The interfaces are set up as DHCP (Dynamic Host Configuration Protocol) by default, meaning they automatically receive the necessary settings from the router. However, if you need to configure a static IP address, follow the on-screen instructions.
Step 3: Verify Firewall Configuration
Once your internet connection is established, the edge device will run a series of tests to verify that the firewall is properly configured. This step is important to ensure that communication won't be blocked.
Note: For detailed firewall requirements, ports, and domains, see the Network Requirements Guide.
Step 4: Activate Your Edge Device
Once the firewall tests have returned and the connection is confirmed, you will be presented with a QR code on the screen. This code needs to be scanned to activate the device with your account.
- Using your phone, scan the QR code
- You will be prompted to log into MachineMetrics if you haven't already done so
- Once logged in, you'll see a form that has been automatically filled out with the activation code. Click "Add Edge Device"
Step 5: Connect to Your Machine Network
Follow on-screen instructions for configuring the edge device to connect a second networking interface to your machine network.
Network Requirements
To ensure reliable operation of your Edge Device, the following network requirements must be met. All communication is edge-initiated outbound—there are no inbound firewall requirements.
Required Ports
| Port | Protocol | Description |
|---|---|---|
| 53 | UDP | DNS resolution |
| 123 | UDP | Network Time Protocol |
| 443 | TCP | HTTPS communication, updates, remote diagnostics |
| 7422 | TCP | NATS communication for tool monitoring and Edge health |
Required Domains and Addresses
The following URLs must be accessible from the Edge Device:
| URL | Description |
|---|---|
| api.machinemetrics.com | MachineMetrics communication |
| app.machinemetrics.com | MachineMetrics communication |
| *.balena-cloud.com | Software updates |
| cloudlink.balena-cloud.com | Remote diagnostics and OS updates |
| notify.bugsnag.com | Bug reporting |
| mm-adapter-store.s3.us-west-2.amazonaws.com | Machine data communication |
| mm-edge-uploads.s3.us-west-2.amazonaws.com | Machine data communication |
| machinemetrics-deploy.s3.us-west-2.amazonaws.com | Machine data communication |
| machinemetrics-public.s3.us-west-2.amazonaws.com | Machine data communication |
| 352302322568.dkr.ecr.us-west-2.amazonaws.com | Software container updates |
| prod-us-west-2-starport-layer-bucket.s3.us-west-2.amazonaws.com | Machine data communication |
GovCloud-Specific Requirements
If you're using MachineMetrics GovCloud, the following domains and static IP addresses must be accessible:
| URL | Description | Static IPs |
|---|---|---|
| api.machinemetrics-us-gov.com | MachineMetrics communication | 18.252.129.108, 18.254.70.116, 182.30.131.220 |
| app.machinemetrics-us-gov.com | MachineMetrics communication | — |
| stream.machinemetrics-us-gov.com:7422 | NATS (tool monitoring and edge health) | See GovCloud NATS IPs below |
| api.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| ca.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| cloudlink.balena.machinemetrics-us-gov.com | Remote diagnostics and OS updates | 18.253.182.20 |
| logs.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| ocsp.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| registry2.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| s3.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| tunnel.balena.machinemetrics-us-gov.com | Software updates | 18.253.182.20 |
| machinemetrics-adapter-store.s3.us-gov-east-1.amazonaws.com | Machine data communication | — |
| machinemetrics-govcloud-edge-uploads.s3.us-gov-east-1.amazonaws.com | Machine data communication | — |
| machinemetrics-deploy.s3.us-gov-east-1.amazonaws.com | Machine data communication | — |
| machinemetrics-govcloud-public.s3.us-gov-east-1.amazonaws.com | Machine data communication | — |
| 139811071765.dkr.ecr.us-gov-east-1.amazonaws.com | Software updates | — |
DNS Configuration
- The Edge Device uses Google DNS (8.8.8.8 and 8.8.4.4) by default
- DNS may be overridden via DHCP or statically in the Edge management page
- If Google DNS is blocked, the Edge will fall back to the configured DNS servers
Network Time Protocol (NTP)
The Edge synchronizes time using the pool.ntp.org fleet:
*.resinio.pool.ntp.org
Internal NTP servers may be specified via DHCP if required. IP-based filtering is not possible due to the distributed nature of public NTP pools.
NATS Communication
NATS requires outbound access to port 7422. The following IP addresses must be reachable:
Standard MachineMetrics:
- 54.218.103.126
- 52.24.16.63
- 52.34.161.223
- 35.155.82.103
GovCloud Only:
- 18.252.129.108
- 18.254.70.116
- 182.30.131.220
Deep Packet Inspection (DPI)
Deep packet inspection must not be applied to any traffic between the Edge Device and the MachineMetrics Cloud, including:
- MachineMetrics domains
- Balena domains
- S3 endpoints
- NATS services
- All encrypted HTTPS traffic
If DPI is enabled (e.g., Palo Alto, Fortinet, Cisco), create bypass rules for Edge traffic.
Proxy Configuration
If your network requires proxy configuration, this can be set during the initial setup or later through the Edge management interface. Consult with your IT team for specific proxy settings.
Bandwidth Requirements
The Edge Device requires minimal bandwidth for normal operation:
- Typical data transmission: 1-5 Mbps
- Software updates: 10-50 MB (periodic)
- Recommended minimum: 10 Mbps connection
Edge-to-Machine Protocol Ports
If a firewall exists between the Edge Device and the machine network, allow outbound access from the Edge to the appropriate protocol ports:
| Protocol / Controller | Port |
|---|---|
| FANUC FOCAS | 8193 |
| Citizen M700 | 683 |
| Mitsubishi | 683 |
| Haas Serial | 4001 |
| Haas MTConnect | 8082 |
| MTConnect Adapter | 7878 |
| MTConnect Agent | 5000 |
| Heidenhain | 19000 |
| Allen Bradley (EtherNet/IP) | 44818 |
| Siemens S7 | 102 |
| MQTT | 1883 |
| OPC-UA | Varies by manufacturer/configuration |
| Bystronic OPC-UA | 56000 |
| Siemens OPC-UA | 4840 |
| Kepware OPC-UA | 49320 |
| Fanuc Robot OPC-UA | 4880 |
| Modbus TCP / SeaLevel | 502 |
Note: OPC-UA port numbers can vary depending on the manufacturer or how users configure their OPC-UA servers. Check with your equipment manufacturer or IT team for specific port configurations.
Verification
How to Confirm Edge is Connected
After completing the activation process:
- Log into your MachineMetrics account
- Navigate to Settings > Edge Devices
- Your newly activated Edge Device should appear in the list with a "Connected" status
- The device page will show:
- Connection status
- IP address
- Software version
- Last communication time
Health Check Indicators
A healthy Edge Device will show:
- Status: Connected (green indicator)
- Last Seen: Within the last few minutes
- Software Version: Current version number
- Network: Both WAN and LAN interfaces configured (if applicable)
Data Retention and Connectivity
MachineMetrics is designed to buffer and retain machine data during common connectivity disruptions. When temporary interruptions occur, the MachineMetrics Edge Device can buffer data locally and backfill retained data once connectivity is restored. This helps preserve continuity in machine timelines, reports, and dashboards.
Key Principle: MachineMetrics can only backfill data that was successfully captured and retained by the Edge Device. Data from extended outages, internal network interruptions, machine disconnections, or hardware failures may be permanently unavailable.
Note on Connectivity Terms
Local network connectivity refers to the connection between machines and the MachineMetrics Edge Device. This is separate from internet connectivity. Machines can stop sending data to the Edge Device even if the Edge Device itself is fully connected to the internet.
How Data Buffering and Backfill Works
When machine data is being successfully received by the MachineMetrics Edge Device:
- Temporary internet interruptions do not typically stop data collection
- Data is buffered locally for a limited period
- Once connectivity is restored, retained data is automatically uploaded and backfilled into MachineMetrics
This buffering and backfill behavior is a core capability of the platform and requires no manual action when conditions are met.
Internet Connectivity Loss
If internet connectivity is lost but the MachineMetrics Edge Device remains powered and continues receiving data from machines over the local network:
- Data is typically buffered locally for a limited period
- Retained data is sent to MachineMetrics once the connection is restored
- In many cases, this results in minimal or no visible data gaps
Important: If machines are unable to send data to the Edge Device during this time, buffering and backfill cannot occur.
Power Loss or Local Network Disruption
If the MachineMetrics Edge Device loses power or if the local network connection between machines and the Edge Device is interrupted:
- Machine data cannot be captured during that time
- This can occur even if the Edge Device itself still has internet connectivity
- Activity that occurs while machines are disconnected is not recoverable
- Data captured before the interruption and after connectivity is restored is retained normally
Internal Network Issues or Machine Disconnections
If internal networking issues prevent machines from sending data to the MachineMetrics Edge Device:
- Data generated during that period is not captured
- This includes unplugged machines, disabled ports, controller changes, switch or VLAN issues, or other internal network misconfigurations
- Data from these periods cannot be recovered later
Ensuring stable internal networking and machine connectivity is required for continuous data capture.
Extended Outages
During extended outages such as prolonged internet loss, repeated restarts, or unstable connectivity, data retention is not guaranteed.
In these situations:
- Some or all data from the outage period may be permanently unavailable
- Recovery depends on whether data was captured and retained throughout the interruption
- MachineMetrics does not guarantee full data recovery after extended interruptions
Summary
- MachineMetrics is designed to buffer data during common connectivity disruptions
- Retained data is automatically backfilled when connectivity is restored
- Data recovery depends on successful capture and retention by the Edge Device
- Extended outages, internal network issues, machine disconnections, or hardware failures can result in permanent data unavailability
Troubleshooting Common Issues
Edge Device Won't Boot
Problem: Device doesn't start or shows a blank screen
Solutions:
- Verify power cable is securely connected
- Check that monitor cable is properly connected
- Try a different power outlet
- If using a thumb drive, ensure it was flashed correctly
Can't Connect to Internet
Problem: Firewall tests fail during setup
Solutions:
- Verify network cable is connected (for Ethernet)
- Check that WiFi password is correct
- Confirm DHCP is enabled on your network, or configure static IP
- Review required firewall ports and domains with your IT team
- Ensure DNS servers are accessible
QR Code Won't Scan
Problem: Mobile device can't read the activation QR code
Solutions:
- Ensure adequate lighting
- Try moving phone closer or farther from the screen
- Clean your phone camera lens
- Manually enter the activation code displayed below the QR code
Device Shows as Offline in Portal
Problem: Edge Device activated but shows offline status
Solutions:
- Check internet connectivity on the Edge Device
- Verify firewall rules allow required outbound connections
- Restart the Edge Device
- Check that the time/date on the Edge is correct (NTP synchronization)
- Contact MachineMetrics support if issue persists
Flashing Process Hangs
Problem: Screen stuck with cursor during flashing
Solutions:
- Wait at least 15 minutes—the process can take time
- If still frozen after 30 minutes, power cycle the device and try again
- Re-flash the thumb drive with a fresh image download
- Verify the thumb drive is at least 16GB and functioning properly
Virtual Edge Stuck on Loading Screen
Problem: Virtual Edge image won't complete startup
Solutions:
- Download a fresh image file (images expire weekly)
- Verify VM has adequate resources allocated (4 cores, 6GB RAM, 64GB storage)
- Check that virtualization platform meets minimum version requirements
- Ensure network adapter is configured correctly in VM settings
Getting Help
If you encounter issues not covered in this troubleshooting section:
- Check the Knowledge Base: Visit support.machinemetrics.com for additional articles
- Contact Support: Submit a ticket through your MachineMetrics portal or email support@machinemetrics.com
- Talk to Your SDM: During onboarding, reach out to your Solution Delivery Manager for assistance
When contacting support, please provide:
- Edge Device serial number or hostname
- Description of the issue
- Screenshots of any error messages
- Network configuration details (if connectivity-related)
Next Steps
Once your Edge Device is successfully activated and online:
- Add Machines: Connect your first machine to begin collecting data
- Configure Network: Set up the machine network interface if not already done
- Verify Data Flow: Confirm that data is being collected from connected machines
- Set Up Users: Add team members and configure their access levels
For guidance on these next steps, refer to:
- Machine Connectivity guides for your specific protocol
- User Management & Access documentation
- Quick Start Checklist