# How CasaOS Manages Periodic Tasks Using Cron: Hardware Status Scheduling Explained

> Discover how CasaOS leverages cron for periodic tasks like hardware status updates. Learn about real-time monitoring and efficient scheduling.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: internals
- Published: 2026-06-26

---

**CasaOS uses the `robfig/cron` library with second-level precision to schedule background jobs, creating independent `cron.Cron` instances that execute functions like `SendAllHardwareStatusBySocket` every five seconds for real-time system monitoring without blocking the main HTTP server.**

The IceWhaleTech/CasaOS repository implements a robust scheduling mechanism for recurring maintenance and monitoring operations. By leveraging the popular `robfig/cron` library, CasaOS can execute periodic tasks such as gathering CPU, memory, and network statistics while keeping the system responsive.

## The Cron Architecture in CasaOS

CasaOS relies on the third-party **`robfig/cron`** library (specifically `github.com/robfig/cron/v3`) rather than the system crontab. This approach provides several advantages: Go-native execution, second-level scheduling precision, and safe concurrent job handling within the application process.

The architecture allows multiple independent cron instances across different packages. Each scheduler runs in its own goroutine, ensuring that hardware monitoring tasks never interfere with HTTP request handling or WebSocket communications.

## Scheduling Hardware Status Updates

The primary periodic task in CasaOS involves collecting comprehensive hardware metrics and broadcasting them via the internal notification bus.

### The Main Scheduler Setup

In **[`main/main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go)**, the application initializes a global cron instance during startup:

```go
crontab := cron.New(cron.WithSeconds())
if _, err := crontab.AddFunc("@every 5s", route.SendAllHardwareStatusBySocket); err != nil {
    logger.Error("add crontab error", zap.Error(err))
}
crontab.Start()

```

The `cron.WithSeconds()` option enables second-level precision, while the `@every 5s` schedule expression ensures the hardware status function executes every five seconds. The `Start()` method launches the scheduler in a background goroutine immediately.

### The Hardware Monitoring Job

The actual data collection logic resides in **[`route/periodical.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/periodical.go)** within the `SendAllHardwareStatusBySocket()` function. This job orchestrates system metric gathering through the `SystemService` interface:

```go
func SendAllHardwareStatusBySocket() {
    // 1. Gather network interface statistics
    netList := service.MyService.System().GetNetInfo()
    // Interface state collection via GetNetState...
    
    // 2. Collect CPU metrics
    cpuPercent := service.MyService.System().GetCpuPercent()
    cpuCores := service.MyService.System().GetCpuCoreNum()
    cpuInfo := service.MyService.System().GetCpuInfo()
    cpuTemp := service.MyService.System().GetCPUTemperature()
    cpuPower := service.MyService.System().GetCPUPower()
    
    // 3. Retrieve memory statistics
    memInfo := service.MyService.System().GetMemInfo()
    
    // 4. Assemble payload
    body := map[string]interface{}{
        "sys_mem": memInfo,
        "sys_cpu": cpuData,
        "sys_net": newNet,
    }
    
    // 5. Publish to notification bus
    service.MyService.Notify().SendNotify("casaos:system:utilization", body)
}

```

The function aggregates data from multiple sources—including network interfaces via `GetNetInfo`, processor utilization via `GetCpuPercent`, and memory statistics via `GetMemInfo`—then publishes the payload under the topic `casaos:system:utilization` using the notification service.

## Additional Periodic Tasks: WebSocket Heartbeat

CasaOS demonstrates architectural flexibility by allowing sub-packages to maintain their own schedulers. In **[`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go)**, a separate cron instance manages WebSocket health checks:

```go
func init() {
    go handler.monitoring()  // Start WebSocket client manager
    
    crontab := cron.New(cron.WithSeconds())
    task := func() { 
        handler.broadcast <- []byte(`{"type":"ping"}`) 
    }
    // Classic cron syntax: every 30 seconds
    crontab.AddFunc("*/30 * * * * ?", task)
    crontab.Start()
}

```

This pattern—using `*/30 * * * * ?` cron syntax alongside the `@every` shorthand—shows that CasaOS supports standard cron expressions with seconds fields. Each independent scheduler handles its own lifecycle, preventing single points of contention.

## Key Implementation Details

- **Second-level precision**: The `cron.WithSeconds()` configuration option enables sub-minute scheduling, critical for real-time hardware monitoring.
- **Goroutine isolation**: Each `crontab.Start()` invocation spawns a separate goroutine, ensuring periodic tasks never block the main application thread.
- **Service layer integration**: Jobs interact with hardware through the `service.System()` interface, abstracting direct system calls into testable service methods.
- **Notification bus**: Rather than tightly coupling to WebSocket handlers, the system uses `service.MyService.Notify().SendNotify()` for decoupled message distribution.

## Summary

- CasaOS uses the **`robfig/cron`** library for in-process task scheduling with second-level precision.
- The main hardware status job runs every **5 seconds** via `@every 5s` schedule in [`main/main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go).
- **[`route/periodical.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/periodical.go)** contains `SendAllHardwareStatusBySocket()`, which gathers CPU, memory, network, and temperature data through `SystemService` methods.
- Multiple independent cron instances (e.g., in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go)) allow fine-grained scheduling without contention.
- Hardware metrics are published to the **`casaos:system:utilization`** topic via the notification bus for decoupled consumption.

## Frequently Asked Questions

### How does CasaOS prevent periodic tasks from blocking the main application?

CasaOS runs each cron scheduler in its own goroutine. When `crontab.Start()` is called, the library spawns a background goroutine that sleeps until the next scheduled execution time, leaving the main HTTP server and other services unblocked.

### What cron library does CasaOS use for background jobs?

CasaOS uses **`github.com/robfig/cron/v3`**, a popular Go library that provides robust cron expression parsing, second-level precision, and thread-safe job execution. This replaces traditional system-level cron for in-application scheduling.

### How often does CasaOS send hardware status updates?

According to the source code in [`main/main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go), CasaOS sends hardware status updates **every 5 seconds** using the `@every 5s` schedule expression. This provides near real-time monitoring of CPU, memory, and network utilization.

### Where does CasaOS publish the collected hardware status data?

The `SendAllHardwareStatusBySocket()` function in [`route/periodical.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/periodical.go) publishes data to the internal notification bus using `service.MyService.Notify().SendNotify()` with the topic **`casaos:system:utilization`**, allowing WebSocket handlers and other subscribers to receive updates without direct coupling to the monitoring logic.