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:

[
    {
        "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:

[
    {
        "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):

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'

Data Models (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

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.

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.

4.1 KiB Raw Blame History