This project provides a backend API to interact with a Philips AC2889/10 air purifier. The API allows you to control the air purifier and observe its status using various endpoints. The backend is designed to run in a Docker container for easy deployment.
- Requirements
- Setup and Configuration
- Status Observer
- API Endpoints
- Running the Observer Process
- Project Structure
- Additional Information
- Python 3.8 or higher
- Docker
- aioairctrl utility for interacting with the air purifier
- FastAPI framework
- Uvicorn ASGI server
Change the .env file in the root directory
- HOST_IP: The IP address of your air purifier on the network.
- LOG_LEVEL: The logging level (ERROR or INFO).
- ORIGINS: CORS Origins.
- WEBSOCKET_URL: URL where the server runs.
To deploy the backend in a Docker container, use the provided scripts.
Run the following command in PowerShell to deploy the container:
cd scripts
.\deploy-container.ps1
Run the following command in a Unix-like terminal to deploy the container:
cd scripts
.\deploy-container.sh
To run the application locally without Docker, follow these steps:
-
Install the required Python packages:
pip install -r requirements.txt
-
Start the FastAPI application:
uvicorn app.main:app --host 0.0.0.0 --port 8000
The status observer process is responsible for periodically fetching the status of the air purifier. This process restarts every 5 minutes to ensure stability.
To run the status observer manually, execute the following command:
python app/services/status_observe.py
- POST /mode_p: Set the air purifier to 'P' mode.
- POST /mode_a: Set the air purifier to 'A' mode.
- POST /turbo: Set the air purifier to turbo mode.
- POST /sleep: Set the air purifier to sleep mode.
- POST /stop: Stop the air purifier.
- POST /start: Start the air purifier.
- GET /status: Retrieve the latest status of the air purifier.
- GET /ws: WebSocket endpoint for real-time status updates.
The observer process continuously monitors the status of the air purifier and restarts every 5 minutes. It can be started manually or is automatically started when running the main application.
.
├── app
│ ├── config.py # Configuration settings
│ ├── main.py # Main FastAPI application
│ ├── routes
│ │ ├── control.py # Control endpoints
│ │ └── status.py # Status endpoint
│ ├── services
│ │ ├── status_observe.py # Status observer service
│ │ └── websocket_manager.py # WebSocket manager service
│ ├── templates
│ │ └── websocket_example.html # WebSocket example HTML
│ └── utils
│ └── globals.py # Global variables and instances
├── models
│ └── status.py # Status model
├── scripts
│ ├── deploy-container.ps1 # PowerShell deployment script
│ ├── deploy-container.sh # Bash deployment script
│ └── remove-container.ps1 # PowerShell remove script (not shown)
├── .env # Environment variables file
├── Dockerfile # Docker configuration file
├── requirements.txt # Python dependencies
└── README.md # Project documentation
This backend is designed specifically for the Philips AC2889/10 air purifier. Due to the instability of the purifier's interface, commands may not always be executed, and status observation may fail. The observer process is restarted every 5 minutes to maintain stability.