# 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`

> **DANGER: 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

> **MEMO: 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:

```json
{
    "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`

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

______________________________________________________________________

## Rename OpenFAN Micro

Endpoint to rename OpenFAN Micro.

> **NOTE: 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

```json
{
    "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

```json
{
    "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

```json
{
    "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

```json
{
    "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%` PWM will result in your fan spinning at the lowest RPM it can achieve.
- Applying `100%` PWM will result in your fan spinning at the highest RPM it can achieve.

> **NOTE: 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

```json
{
    "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.

> **NOTE: 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

```json
{
    "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.

> **NOTE: 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

```json
{
    "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

```json
{
    "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](https://docs.sasakaranovic.com/openfan_micro/setup/index.md))

### Example

> `GET` - `/api/v0/wifi/reset?confirm=true`

Response is a JSON object

```json
{
    "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/device/reboot?confirm=true`

Response is a JSON object

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

______________________________________________________________________
