/
Edge service installation, usage and maintenance guide

Edge service installation, usage and maintenance guide

Overview

The VibCloud Edge Service is a lightweight software package that runs on a Raspberry Pi at your site. It acts as the bridge between your local vibration sensor gateway and the VibCloud cloud platform — automatically collecting sensor data, compressing it, and uploading it to VibCloud for analysis and monitoring.

Feature

Description

Feature

Description

Automatic Sensor Sync

Fetches your sensor configuration from VibCloud and configures the local gateway — no manual setup per sensor.

Continuous Upload

Collects and uploads sensor data on a configurable interval with automatic retry on failure.

Health Monitoring

Built-in watchdog automatically recovers from hangs. Health status available via CLI, web, and HTTP endpoint.

Web Dashboard

Browser-based interface for status monitoring, sensor management, log viewing, and settings — accessible from any device on the network.

CLI Management

Full command-line control via vibcloud-ctl for scripting, SSH management, and automation.

Zero-Downtime Config

Change settings in the .env file and they apply automatically — no service restart needed.

How It Works

The service runs as a background process (systemd daemon) with three main responsibilities:

  1. Sensor Synchronisation — on demand, it contacts the VibCloud API to fetch your sensor list, then configures each sensor on the local gateway.

  2. Data Upload — once sensors are configured, it continuously reads data from the gateway, compresses it, and uploads it to VibCloud.

  3. Self-Monitoring — the service monitors its own health and automatically restarts components that stall. If the entire service becomes unresponsive, systemd will restart it.

SCREENSHOT: Architecture Diagram

VibCloud Architecture - Cloud.png

 

Prerequisites

Before installing, ensure you have the following ready:

Requirement

Details

Requirement

Details

Raspberry Pi

Model 3B+ or newer recommended. Running Raspberry Pi OS (Bookworm / Debian 12 or older).

Python

Version 3.7 or higher (pre-installed on most Raspberry Pi OS images).

Network

Internet access for cloud API communication. Local network access to the sensor gateway device.

Sensor API

A compatible vibration sensor API accessible on the local network (e.g. http://192.168.1.100:8080/).

VibCloud Account

You will need your Client ID, Cloud API URL, and API Key. Contact iTnnovate support if you do not have these.

Bookworm CompatibilityThe installer creates an isolated Python virtual environment, so it works on Raspberry Pi OS Bookworm (Debian 12) without conflicting with system packages. No --break-system-packages flag needed.

Installation

Fresh Install

Follow these steps to install the VibCloud Edge Service for the first time.

1. Transfer the Package to the Raspberry Pi

Copy the vibcloud-edge-service.zip file to the Raspberry Pi using SCP, a USB drive, or your preferred method.

# From your local machine: $ scp vibcloud-edge-service.zip pi@<raspberry-pi-ip>:~/

2. Extract & Run the Installer

SSH into the Raspberry Pi and run the installation script. It will install system dependencies, create a Python virtual environment, and set up systemd services.

$ ssh pi@<raspberry-pi-ip> $ unzip vibcloud-edge-service.zip $ cd vibcloud-edge-service $ chmod +x install.sh $ ./install.sh

SCREENSHOT: Installer Output

image-20260210-132616.png

 

3. Create Your Configuration File

Copy the example configuration and fill in your site-specific values:

$ cd ~/vibcloud-service $ cp .env.example .env $ nano .env

Update the following required settings:

Setting

Description

Example

Setting

Description

Example

CLIENT_ID

Your VibCloud client identifier

201

SENSOR_API_URL

Local sensor gateway address

http://192.168.1.100:8080/

CLOUD_API_URL

VibCloud cloud API endpoint

https://your-instance.azurewebsites.net/api/

CLOUD_API_KEY

Your API authentication key

Provided by iTnnovate

Keep your API key secure.The .env file contains credentials and should never be shared or committed to version control.

4. Sync Sensors & Start the Service

Fetch your sensor configuration from VibCloud and start the service:

# Pull sensor list from VibCloud $ vibcloud-ctl sync # Verify sensors are configured $ vibcloud-ctl sensors # Start the service $ sudo systemctl start vibcloud # Enable auto-start on boot (recommended) $ sudo systemctl enable vibcloud

SCREENSHOT: vibcloud-ctl sensors Output

image-20260210-134629.png

 

5. Verify Everything Is Running

$ vibcloud-ctl status $ vibcloud-ctl health

You should see the service in a RUNNING state with all health components showing HEALTHY.

Daily Operations

Once installed, the VibCloud Edge Service runs automatically in the background. This section covers the tools available for day-to-day management.

CLI Reference — vibcloud-ctl

The vibcloud-ctl command is available from any directory on the Raspberry Pi. It is the primary tool for managing the service over SSH.

Command

Description

Command

Description

vibcloud-ctl status

Show current service state, uptime, sensor count, and upload statistics.

vibcloud-ctl health

Detailed health report with per-component status (main loop, upload worker, database).

vibcloud-ctl sync

Fetch the latest sensor configurations from VibCloud and apply them to the local gateway.

vibcloud-ctl sensors

List all sensors with status indicators: ✅ configured, ⏳ pending, ❌ failed.

vibcloud-ctl logs

View the most recent service log entries.

vibcloud-ctl start

Start the service (equivalent to sudo systemctl start vibcloud).

vibcloud-ctl stop

Stop the service gracefully.

vibcloud-ctl restart

Stop and start the service.

vibcloud-ctl enable

Enable auto-start on boot.

vibcloud-ctl disable

Disable auto-start on boot.

Web Interface

The web dashboard provides a visual interface for monitoring and managing the service from any browser on the same network.

Access: http://<raspberry-pi-ip>:5000

If the web interface was installed as a systemd service during setup, it starts automatically. Otherwise, start it manually:

$ vibcloud-web

Dashboard

The main dashboard displays the current service state, number of configured sensors, upload statistics, and error counts at a glance.

SCREENSHOT: Web Dashboard

image-20260210-135040.png

 

Sensor List

View all sensors with their configuration status, last activity, and any error messages.

SCREENSHOT: Sensor List View

image-20260210-135115.png

 

Settings

Edit service configuration directly from the browser. Changes are saved to the .env file and applied automatically.

SCREENSHOT: Settings Page

image-20260210-135241.png

 

Log Viewer

View recent log output with auto-refresh, useful for monitoring operations in real time.

SCREENSHOT: Log Viewer

image-20260210-135353.png

 

Web API Endpoints

The web interface also exposes a REST API for integration with external monitoring tools.

Endpoint

Method

Description

Response

Endpoint

Method

Description

Response

/api/health

GET

Health check endpoint

200 if healthy, 503 if unhealthy

/api/status

GET

Full service status and statistics

JSON with state, uptime, sensor counts, upload stats

/api/sensors

GET

List all sensors

JSON array of sensor objects

/api/sync

POST

Trigger sensor synchronisation

JSON with sync result

/api/config

GET / POST

Read or update configuration

JSON with current settings

/api/logs

GET

Retrieve recent log lines

JSON with log entries

/api/service/<action>

POST

Start, stop, or restart service

JSON with result

/api/autostart

GET / POST

Check or toggle auto-start

JSON with autostart state

External monitoring tip:Use the /api/health endpoint with your existing monitoring tools (e.g. Uptime Kuma, Nagios, PRTG). A 200 response means the service is operating normally. A 503 indicates a problem that needs attention.

Health Monitoring

The VibCloud Edge Service includes a multi-layer health monitoring system designed to keep the service running reliably without manual intervention.

How It Works

Layer

What It Does

Recovery Action

Layer

What It Does

Recovery Action

Internal Watchdog

The daemon tracks three components (main_loop, upload_worker, database). Each reports a heartbeat. If the upload thread stops responding for 10 minutes, the daemon detects the stall.

Automatically restarts the upload thread.

systemd Watchdog

The service runs with WatchdogSec=90. The daemon pings systemd every ~5 seconds. If systemd receives no ping within 90 seconds, it considers the entire process hung.

systemd kills and restarts the service.

systemd Restart Policy

If the service crashes for any reason, systemd's Restart=always policy will bring it back.

Automatic restart after 10-second delay.

Heartbeat File

The daemon writes a healthcheck.json file every 10 seconds with full component status.

Readable by external monitoring tools, the web dashboard, and the CLI.

Checking Health

Via CLI

$ vibcloud-ctl health ============================================================ VibCloud Service Health Check ============================================================ ✅ Overall: HEALTHY Uptime: 2:14:03 Last heartbeat: 2026-02-10T14:30:00 📋 Components (3): ✅ main_loop: healthy Last seen: 4.2s ago | Failures: 0 Message: Loop running ✅ upload_worker: healthy Last seen: 12.1s ago | Failures: 0 Message: Cycle 847 OK ✅ database: healthy Last seen: 4.2s ago | Failures: 0 ============================================================

Via HTTP

$ curl -s http://localhost:5000/api/health | python3 -m json.tool

Health Status Meanings

Status

Meaning

Action Required?

Status

Meaning

Action Required?

HEALTHY

All components operating normally.

No — everything is fine.

DEGRADED

One or more components have experienced failures but are still running.

Monitor — check logs for errors. Usually self-recovers.

UNHEALTHY

A component has stopped responding or has persistent failures.

Yes — investigate with vibcloud-ctl logs and consider restarting.

Maintenance

Upgrading

To upgrade to a new version, simply transfer the new package and re-run the installer. The upgrade process is designed to be safe and non-disruptive:

# Transfer new version to the Pi $ scp vibcloud-edge-service.zip pi@<raspberry-pi-ip>:~/ # SSH in and run the installer $ ssh pi@<raspberry-pi-ip> $ unzip -o vibcloud-edge-service.zip $ cd vibcloud-edge-service $ ./install.sh

The installer will automatically:

  1. Detect the existing installation and display the current version.

  2. Stop running services.

  3. Back up your .env, database, and state files to a timestamped backup folder.

  4. Replace application code while preserving your configuration, database, logs, and virtual environment.

  5. Update Python dependencies if requirements.txt has changed.

  6. Restart services that were previously enabled.

Your configuration and data are preserved. The upgrade only replaces application code. Your .env settings, sensor database, and logs are untouched. A backup is created as an extra precaution.

Log Management

All log files use automatic rotation to prevent disk space issues on the Raspberry Pi:

Log File

Source

Rotation

Log File

Source

Rotation

logs/vibcloud_service.log

Main service daemon

5 MB × 3 backups

logs/vibcloud_upload.log

Standalone upload process

5 MB × 3 backups

logs/vibcloud_edge_service.log

Standalone sensor manager

5 MB × 3 backups

Maximum disk usage for logs:

~45 MB total. Rotation is fully automatic — no manual cleanup needed.

 

You can also view logs through the system journal:

# Follow live logs $ sudo journalctl -u vibcloud -f # View last 100 log entries $ sudo journalctl -u vibcloud -n 100 --no-pager

The log level can be changed without restarting the service by editing the LOG_LEVEL setting in .env. Available levels: DEBUG, INFO (default), WARNING, ERROR, CRITICAL.

Backup & Recovery

The most important files to back up are:

File

What It Contains

File

What It Contains

~/vibcloud-service/.env

All configuration settings and API credentials.

~/vibcloud-service/vibcloud.db

Sensor configurations, history, and upload records.

To create a manual backup:

$ mkdir -p ~/vibcloud-backup $ cp ~/vibcloud-service/.env ~/vibcloud-backup/ $ cp ~/vibcloud-service/vibcloud.db ~/vibcloud-backup/

To restore after a fresh install, copy these files back to ~/vibcloud-service/ and restart the service.

Uninstalling

To completely remove the VibCloud Edge Service:

$ cd vibcloud-edge-service $ chmod +x uninstall.sh $ ./uninstall.sh

The uninstall script will stop all services, remove systemd files and CLI tools, and create a backup of your configuration and database before removing the installation directory.

Troubleshooting

Service won't start

# Check service status for error messages $ sudo systemctl status vibcloud # View detailed logs $ sudo journalctl -u vibcloud -n 100 --no-pager # Run health check $ vibcloud-ctl health

Common causes: missing .env file, incorrect API URL, or sensor gateway not reachable.

Upload not starting

The upload process only starts when the database contains configured sensors:

# Check if sensors are configured $ vibcloud-ctl sensors # If no sensors, sync from cloud $ vibcloud-ctl sync

Health check shows DEGRADED or UNHEALTHY

# See which component is failing $ vibcloud-ctl health # Check recent logs for errors $ vibcloud-ctl logs # Force restart if needed $ sudo systemctl restart vibcloud

Web interface not accessible

# Check if web service is running $ sudo systemctl status vibcloud-web # Check if port 5000 is in use $ sudo netstat -tlnp | grep 5000 # Open firewall if needed $ sudo ufw allow 5000

Sensor gateway not reachable

# Test connectivity to the gateway $ curl -v http://<gateway-ip>:8080/ # Check your .env setting $ grep SENSOR_API_URL ~/vibcloud-service/.env

Still stuck? Collect the output of vibcloud-ctl status, vibcloud-ctl health, and the last 200 journal lines (sudo journalctl -u vibcloud -n 200 --no-pager), then contact iTnnovate support.

Configuration Reference

All settings are configured in the ~/vibcloud-service/.env file. Changes are detected automatically — no service restart needed in most cases.

Required Settings

Setting

Description

Example

Setting

Description

Example

CLIENT_ID

Your VibCloud client identifier.

101

DATABASE_FILE

Local SQLite database filename.

vibcloud.db

SENSOR_API_URL

Local sensor gateway URL.

http://192.168.1.100:8080/

CLOUD_API_URL

VibCloud cloud API endpoint.

https://your-instance.azurewebsites.net/api/

CLOUD_API_KEY

API authentication key.

Provided by iTnnovate

SENSOR_SCHEDULE_MIN

Sensor data collection interval (minutes).

5

Optional Settings

Setting

Default

Description

Setting

Default

Description

UPLOAD_INTERVAL_SECONDS

60

How often to upload data (seconds).

UPLOAD_BATCH_SIZE

10

Number of sensors per upload batch.

MAX_UPLOAD_RETRIES

3

Retry attempts for failed uploads.