Telemetry Data
Raw telemetry data management — statistics, reports, data lifecycle operations, and debug tools.
Base Route: /api/sunsourcedata
Authorization: Omni policy (User, Admin, or Overseer)
Get Statistics
Returns telemetry statistics for all Sun Sources owned by the user. Includes latest readings and message counts per source.
GET /api/sunsourcedata/stats
Response 200 OK
[
{
"sunSourceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"sunSourceName": "Roof Array Alpha",
"messageCount": 145230,
"lastMessageTime": "2025-06-20T14:22:00Z",
"batteryVoltage": 52.4,
"stateOfCharge": 87.5,
"solarPower": 3200.0,
"loadPercentage": 45.2,
"operatingMode": "Solar",
"deviceStatus": "Normal",
"faultCodes": []
}
]
Get Status
Returns the last message timestamp for each Sun Source owned by the user.
GET /api/sunsourcedata/status
Response 200 OK
[
{
"sunSourceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"lastMessageTime": "2025-06-20T14:22:00Z"
}
]
Get Document Count
Returns the total number of telemetry documents stored for a Sun Source.
GET /api/sunsourcedata/count/{sunSourceId}
Response 200 OK
{
"count": 145230
}
Get Storage Size
Returns the storage size in bytes for a Sun Source's telemetry data in MongoDB.
GET /api/sunsourcedata/size/{sunSourceId}
Response 200 OK
{
"sizeBytes": 52428800
}
Generate Report
Returns a comprehensive data report for a Sun Source over the specified period.
GET /api/sunsourcedata/report/{sunSourceId}?period=today
GET /api/sunsourcedata/report/{sunSourceId}?period=custom&startDateParam=2025-06-01&endDateParam=2025-06-15
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
period | string | "today" | Report period: today, yesterday, week, month, custom |
startDateParam | DateTime | — | Required when period=custom |
endDateParam | DateTime | — | Required when period=custom |
Period Definitions
| Period | Start | End |
|---|---|---|
today | Start of today (UTC) | Now |
yesterday | Start of yesterday | End of yesterday |
week | 7 days ago | Now |
month | 30 days ago | Now |
custom | startDateParam | endDateParam |
Response 200 OK
{
"source": {
"name": "Roof Array Alpha",
"iconUrl": "https://minio.ampra.solar/uploads/user123/image.png"
},
"period": "week",
"startDate": "2025-06-13T00:00:00Z",
"endDate": "2025-06-20T14:22:00Z",
"generatedAt": "2025-06-20T14:22:00Z",
"dataPoints": 10080,
"summary": {
"avgSolarPower": 2100.5,
"maxSolarPower": 4800.0,
"avgLoadPower": 1200.3,
"maxLoadPower": 3500.0,
"avgStateOfCharge": 72.5,
"minStateOfCharge": 15.0,
"maxStateOfCharge": 100.0,
"avgBatteryVoltage": 51.8,
"avgBatteryTemperature": 35.2,
"maxBatteryTemperature": 42.0,
"totalEnergyProduced": 147.5,
"totalEnergyConsumed": 98.2,
"avgGridVoltage": 230.5,
"avgGridFrequency": 50.01,
"stateOfHealth": 98.5,
"operatingModes": [
{ "mode": "Solar", "count": 8500, "percentage": 84.3 },
{ "mode": "Battery", "count": 1200, "percentage": 11.9 },
{ "mode": "Grid", "count": 380, "percentage": 3.8 }
]
},
"hourlyData": [
{
"timestamp": "2025-06-20T00:00:00Z",
"solarPower": 0.0,
"loadPower": 450.0,
"stateOfCharge": 85.0,
"batteryVoltage": 52.1,
"batteryTemperature": 28.0,
"gridVoltage": 230.2,
"dailyEnergyProduced": 0.0,
"dailyEnergyConsumed": 0.45
}
]
}
Cleanup Data
Removes all telemetry data for a Sun Source from MongoDB.
DELETE /api/sunsourcedata/cleanup/{sunSourceId}
Response 200 OK
{
"message": "Cleanup completed.",
"deletedCount": 145230
}
This operation is irreversible. All telemetry history for the source is permanently deleted.
Downsample Data
Reduces telemetry data density by aggregating high-frequency samples into lower-frequency summaries. Preserves data integrity while reducing storage.
POST /api/sunsourcedata/downsample/{sunSourceId}
Response 200 OK
{
"message": "Downsample completed.",
"before": 145230,
"after": 52100
}
Debug: Generate Test Data
Generates 30 days of synthetic telemetry data for testing purposes. Admin or Overseer only.
POST /api/sunsourcedata/debug/generate/{sunSourceId}
Response 200 OK
{
"message": "Debug data generated.",
"dataPoints": 43200
}
Debug: Start Simulated MQTT Stream
Starts a background process that continuously generates and writes simulated telemetry data. Admin or Overseer only.
POST /api/sunsourcedata/debug/process/start/{sunSourceId}
Response 200 OK
{
"running": true,
"message": "Debug process started."
}
Debug: Stop Simulated MQTT Stream
Stops the background data generation process. Admin or Overseer only.
POST /api/sunsourcedata/debug/process/stop/{sunSourceId}
Response 200 OK
{
"running": false,
"message": "Debug process stopped."
}
Debug: Get Process Status
Returns whether a simulation process is running and how many data points have been sent. Admin or Overseer only.
GET /api/sunsourcedata/debug/process/status/{sunSourceId}
Response 200 OK
{
"running": true,
"sentCount": 1500
}
Response Schemas
interface SunSourceStatsDto {
sunSourceId: string;
sunSourceName: string;
messageCount: number;
lastMessageTime: string | null;
batteryVoltage: number | null;
stateOfCharge: number | null;
solarPower: number | null;
loadPercentage: number | null;
operatingMode: string | null;
deviceStatus: string | null;
faultCodes: string[] | null;
}
interface ReportDataDto {
source: { name: string; iconUrl: string };
period: string;
startDate: string;
endDate: string;
generatedAt: string;
dataPoints: number;
summary: ReportSummaryDto | null;
hourlyData: ReportHourlyDataDto[];
}
interface ReportSummaryDto {
avgSolarPower: number;
maxSolarPower: number;
avgLoadPower: number;
maxLoadPower: number;
avgStateOfCharge: number;
minStateOfCharge: number;
maxStateOfCharge: number;
avgBatteryVoltage: number;
avgBatteryTemperature: number;
maxBatteryTemperature: number;
totalEnergyProduced: number;
totalEnergyConsumed: number;
avgGridVoltage: number;
avgGridFrequency: number;
stateOfHealth: number;
operatingModes: OperatingModeBreakdownDto[];
}
interface DownsampleResultDto {
message: string;
before: number;
after: number;
}