Skip to content

OpenFAN Micro API Documentation

OpenFAN Micro provides an API that allows you to interact with it remotely or integrate it into another system.

You can use this for example to monitor/log the fan RPM, or to set fan speed based on system temperature/load etc. You could also use it for detection of stalled/blocked fans or to coordinate multiple OpenFan Micro instances.

Accessing web API

The API server runs on port 80, same as the Web UI and accepts HTTP GET requests.
In order to make API requests, you will either use the OpenFAN Micro IP address or mDNS host name.

For example if OpenFAN Micro has the IP of 192.168.0.150 and mDNS host name of myopenfan, the base API address will be accessed in two ways

  • http://192.168.0.150/api/v0
  • http://uopenfan-myopenfan.local/api/v0

Security!

Currently OpenFAN Micro API does NOT use encryption or authentication.
It is advised to limit access to the Web API on your network.

Messaging

Notation!

The web API is provided by OpenFAN Micro which we will call server.
And we will call the device that is making a request (ie your script, automation etc) a client.
Endpoint is the location where API server is listening for API requests.

All transactions begin with the client sending a HTTP/GET request to one of the OpenFAN API server endpoints.

All responses from the server are JSON formatted and always contain keys status.
The message and/or data key will be provided depending on which endpoint is used.
For example request to rename the device will have a message key to indicate success/failure and if endpoint is supposed to provide data back (ie. device status, fan RPM etc) then it will contain data key.

Response has the following structure:

{
    "status": "...",
    "message": "...",
    "data": { }
}

OpenFAN Micro status

Endpoint to get OpenFAN Micro status/configuration information:

  • act_led_enabled - Is activity LED blinking
  • fan_is_12v - Is fan power configured for 12V or 5V

Example

GET - http://192.168.0.150/api/v0/openfan/status

{
    "status": "ok",
    "data": {
        "act_led_enabled": "true",
        "fan_is_12v": "true"
    }
}

Rename OpenFAN Micro

Endpoint to rename OpenFAN Micro.

Device Name Allowed characters

Please note that your device name must be between 3 and 12 characters and can only contain:
- A-Z characters
- 0-9 numbers

Example: Rename OpenFAN Micro to RouterFan:

GET - http://192.168.0.150/api/v0/openfan/name/set?name=routerfan

Response is a JSON object

{
    "status": "ok",
    "message": "Device renamed. Restarting to apply...",
}

Enable activity LED`

Endpoint to enable activity LED.
When enabled white LED will blink every 1s to indicate activity.

Example

GET - http://192.168.0.150/api/v0/led/enable

Response is a JSON object

{
    "status": "ok",
    "message": "Activity LED enabled",
}

Disable activity LED`

Endpoint to disable activity LED.
When disabled white LED will always stay off.

Example

GET - http://192.168.0.150/api/v0/led/disable

Response is a JSON object

{
    "status": "ok",
    "message": "Activity LED disabled",
}

Read fan status (RPM and PWM)

Endpoint to get the latest fan RPM and PWM values.

Example

GET - http://192.168.0.150/api/v0/fan/status

Response is a JSON object

{
    "status": "ok",
    "data": {
            "rpm": 1200,
            "pwm_percent": 80
        }
}

The RPM is the current speed of the fan (calculated revolutions per minute).
The PWM percent is current PWM value (0-100) that is provided to the fan to control the speed.

Set fan PWM value

Endpoint to apply 0-100% PWM signal to the FAN

  • Applying 0% PMW will result in your fan spinning at the lowest RPM it can achieve.
  • Applying 100% PMW will result in your fan spinning at the highest RPM it can achieve.

PWM values

Depending on the fan manufacturer 0% PWM signal will completely stop the fan or run it at very low RPM.

Example: Set fan PWM to 30%

GET - /api/v0/fan/0/set?value=30

Response is a JSON object

{
    "status": "ok",
    "message": "Setting PWM to 30",
}

Switch fan voltage to 12V

Endpoint to switch fan VCC to 12V.
The confirm parameter is required in order to prevent accidentally changing the fan voltage.

Fan voltage

Setting the incorrect fan voltage could potentially damage your fan.

Example

GET - /api/v0/fan/voltage/high?confirm=true

Response is a JSON object

{
    "status": "ok",
    "message": "Switching fan output to 12V",
}

Switch fan voltage to 5V

Endpoint to switch fan VCC to 5V.
The confirm parameter is required in order to prevent accidentally changing the fan voltage.

Fan voltage

Setting the incorrect fan voltage could potentially damage your fan.

Example

GET - /api/v0/fan/voltage/low?confirm=true

Response is a JSON object

{
    "status": "ok",
    "message": "Switching fan output to 5V",
}

Get WiFi information

Endpoint to get OpenFAN Micro WiFi information like

  • WiFi SSID
  • RSSI
  • WiFi Channel

Example

GET - /api/v0/wifi/info

Response is a JSON object

{
    "status": "ok",
    "data": {
            "SSID": "YourWiFiNetworkName",
            "RSSI": -55,
            "CH": 4
        }
}

Reset WiFi

Endpoint to reset/clear WiFi configuration.
The confirm parameter is required in order to prevent accidentally resetting the WiFi configuration.
After calling this endpoint, you will have to setup WiFi again (see setup)

Example

GET - /api/v0/wifi/reset

Response is a JSON object

{
    "status": "ok",
    "message": "WiFi configuration has been reset. Please connect to OpenFAN Micro WiFi and re-configure the device.",
}

Reboot device

Endpoint to reboot OpenFAN Micro.
The confirm parameter is required in order to prevent accidentally rebooting the device.
After calling this endpoint, it might take couple of seconds for the OpenFAN Micro to come online.

Example

GET - /api/v0/wifi/reboot

Response is a JSON object

{
    "status": "ok",
    "message": "Device reboot request received. Rebooting...",
}