130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
# Android App Integration Guide Dashboard Proxy
|
|
|
|
This document outlines how to build an Android application that consumes the data provided by your AC Infinity Proxy API.
|
|
|
|
## Base Configuration
|
|
|
|
* **Base URL**: `https://dev.seedheads.de/ac/`
|
|
* **Protocol**: HTTPS
|
|
|
|
## API Endpoints
|
|
|
|
The proxy server exposes two main endpoints that return JSON data.
|
|
|
|
### 1. Get All Devices
|
|
Retrieves a list of all devices and their ports currently stored in the database.
|
|
|
|
* **Endpoint**: `GET /api/devices`
|
|
* **Full URL**: `https://dev.seedheads.de/ac/api/devices`
|
|
* **Response Format**: JSON Array
|
|
* **Example Response**:
|
|
```json
|
|
[
|
|
{
|
|
"dev_name": "Tent Controller",
|
|
"port": 1,
|
|
"port_name": "Fan Inline"
|
|
},
|
|
{
|
|
"dev_name": "Tent Controller",
|
|
"port": 2,
|
|
"port_name": "Light Top"
|
|
}
|
|
]
|
|
```
|
|
|
|
### 2. Get Historical Data
|
|
Retrieves historical sensor readings for a specific device and port.
|
|
|
|
* **Endpoint**: `GET /api/history`
|
|
* **Full URL**: `https://dev.seedheads.de/ac/api/history`
|
|
* **Query Parameters**:
|
|
* `devName` (string, required): The name of the controller (e.g., "Tent Controller"). URL-encoded.
|
|
* `port` (integer, required): The port number (e.g., `1`).
|
|
* `range` (string, optional): The time range. Defaults to `day`.
|
|
* `day`: Last 24 hours.
|
|
* `week`: Last 7 days.
|
|
* `month`: Last 30 days.
|
|
|
|
* **Example Request**:
|
|
`GET https://dev.seedheads.de/ac/api/history?devName=Tent%20Controller&port=1&range=day`
|
|
|
|
* **Response Format**: JSON Array of objects
|
|
* **Example Response**:
|
|
```json
|
|
[
|
|
{
|
|
"timestamp": "2023-10-27T10:00:00Z",
|
|
"temp_c": 24.5,
|
|
"humidity": 60.2,
|
|
"vpd": 1.1,
|
|
"fan_speed": 5,
|
|
"on_speed": 0,
|
|
"off_speed": 0
|
|
},
|
|
...
|
|
]
|
|
```
|
|
*Note: Timestamps are returned in UTC (ending in 'Z'). You must convert them to the local timezone within the Android app.*
|
|
|
|
## Android Implementation Recommendations
|
|
|
|
### Networking Library
|
|
Use **Retrofit** with **OkHttp** for robust networking. It simplifies URL handling, parameter encoding, and JSON parsing.
|
|
|
|
**Dependencies (`build.gradle`):**
|
|
```groovy
|
|
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
|
|
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
|
|
```
|
|
|
|
### Data Models (Kotlin)
|
|
|
|
```kotlin
|
|
data class Device(
|
|
@SerializedName("dev_name") val devName: String,
|
|
@SerializedName("port") val port: Int,
|
|
@SerializedName("port_name") val portName: String
|
|
)
|
|
|
|
data class Reading(
|
|
val timestamp: String,
|
|
@SerializedName("temp_c") val tempC: Float,
|
|
@SerializedName("humidity") val humidity: Float,
|
|
@SerializedName("vpd") val vpd: Float,
|
|
@SerializedName("fan_speed") val fanSpeed: Int
|
|
)
|
|
```
|
|
|
|
### Retrofit Service Interface
|
|
|
|
```kotlin
|
|
interface AcApi {
|
|
@GET("api/devices")
|
|
suspend fun getDevices(): List<Device>
|
|
|
|
@GET("api/history")
|
|
suspend fun getHistory(
|
|
@Query("devName") devName: String,
|
|
@Query("port") port: Int,
|
|
@Query("range") range: String = "day"
|
|
): List<Reading>
|
|
}
|
|
```
|
|
|
|
### Handling Timezones
|
|
Since the API returns UTC timestamps (e.g., `2023-10-27T10:00:00Z`), use `java.time` (API 26+) to format them for the user's local device time.
|
|
|
|
```kotlin
|
|
val instant = Instant.parse(reading.timestamp)
|
|
val localDateTime = LocalDateTime.ofInstant(instant, ZoneId.systemDefault())
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
* **Authentication**: Currently, the proxy at `https://dev.seedheads.de/ac/` is publicly accessible (if not protected by Basic Auth in Nginx). If you add Basic Auth to Nginx, you will need to add an `Authorization` header to your Retrofit client.
|
|
* **HTTPS**: Ensure your Android app allows HTTPS connections (default behavior).
|
|
|
|
## Future Enhancements
|
|
* **Push Notifications**: The current API is poll-based. For real-time alerts (e.g., high temp), you would need to implement a background worker in Android (`WorkManager`) to poll the API periodically, or implement Firebase Cloud Messaging (FCM) on the Node.js server.
|