Integrating your microcontroller

There are multiple ways to interface a microcontroller or single-board computer with the VanTurtle fan controller. All communication is performed over I²C, and the controller itself is agnostic to the platform as long as basic I²C read and write operations are supported.

This page documents both the officially supported library options and some community implementations. If none of these fit your requirements, the protocol documentation can be used to implement a custom driver or integration.

Python library

The Python library is intended for Linux-based systems such as the Raspberry Pi, but can also be adapted for other platforms that expose an SMBus-compatible I²C interface. It can also be used with micropython for embedded programming.

It provides a high-level abstraction over the raw protocol and exposes fan functions as simple method calls. Example usage:

# Initialize the VanTurtle_Fan controller
# Bus 1 is the default on raspberry pi 5
# 0x27 is the address if A0, A1 and A2 are not connected
# Connects to the left fan on the PCB, labelled FAN ONE
fan = VanTurtle_RJ45(bus=1, address=0x27, fan=VanTurtle_Fan.FAN_ONE)

# Turn the fan on
fan.onoff()

# Reverse airflow direction
fan.reverse()
# Increase the speed
fan.faster()
# Decrease the speed
fan.slower()

# Check if the fan is in temperature hold mode
print(fan.is_autohold())
# Enable temperature hold mode
fan.auto()

# Make a beeping noise
fan.beep()

Based on smbus for I²C communication, make sure that is installed on the system:

pip install smbus2

On most Raspberry Pi OS installations, I²C must also be enabled through raspi-config.

ESP32 C/C++ component

Made to integrate with an ESP-IDF project specifically. Export the folder to the components folder within your project. Make sure your CMakeLists.txt includes vanturtlefan.c in the SRC. Example usage:

#include "vanturtlefan.h"
vanturtlefan_t fan_controller;

// Initialize with default I2C address (0x27) and SDA on pin 21 and SCL on pin 22
vanturtlefan_init(&fan_controller, I2C_NUM_0, 21, 22, 0x27, false);

// Turn the fan connected to the left port on or off
// Exacts an RJ45 connection
vanturtlefan_rj45_onoff(&fan_controller, FAN_ONE);

// Increase speed
vanturtlefan_rj45_faster(&fan_controller, FAN_ONE);
// Decrease speed
vanturtlefan_rj45_slower(&fan_controller, FAN_ONE);
// Reverse airflow direction
vanturtlefan_rj45_reverse(&fan_controller, FAN_ONE);
// Toggle auto mode
vanturtlefan_rj45_auto(&fan_controller, FAN_ONE);
// Make a beep
vanturtlefan_rj45_beep(&fan_controller, FAN_ONE);

// Check if auto mode is enabled
bool autohold_state;
vanturtlefan_is_autohold(&fan_controller, FAN_ONE, &autohold_state);

// In this example, FAN_TWO uses an RJ11 connection
// Turn on or cycle through speeds
vanturtlefan_rj11_on(&fan_controller, FAN_TWO);
// Open lid
vanturtlefan_rj11_open(&fan_controller, FAN_TWO);
// Close lid
vanturtlefan_rj11_close(&fan_controller, FAN_TWO);
// Turn off
vanturtlefan_rj11_off(&fan_controller, FAN_TWO);

// When done, deinitialize the controller
vanturtlefan_deinit(&fan_controller);

ESPHome

This ESPHome config was made by a community member and allows you to add the controller into Home Assistant very quickly. Make sure to read through the file to change some details like wifi name etc.