https://github.com/srcfl/srcful-data-models
https://github.com/srcfl/srcful-data-models
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/srcfl/srcful-data-models
- Owner: srcfl
- Created: 2026-02-03T09:40:46.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-03T23:34:55.000Z (4 months ago)
- Last Synced: 2026-02-04T11:50:17.495Z (4 months ago)
- Language: TypeScript
- Size: 72.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @srcful/data-models
TypeScript definitions for Sourceful Energy DER (Distributed Energy Resource) metadata and telemetry.
## Installation
```bash
npm install @srcful/data-models
```
## Usage
```typescript
import {
DERType,
V2XStatus,
PVMetadata,
PVTelemetry,
BatteryMetadata,
BatteryTelemetry,
DERModel,
} from '@srcful/data-models';
// Define metadata (static configuration)
const pvMetadata: PVMetadata = {
installed_power_W: 12000,
enabled: true,
controllable: true,
};
// Define telemetry (live measurements)
const pvTelemetry: PVTelemetry = {
W: -7500, // Negative = generating
mppt: [
{ V: 380, A: 12.5 },
{ V: 375, A: 7.5 },
],
timestamp: Date.now(),
};
```
## DER Types
| Type | Description | Metadata | Telemetry |
|------|-------------|----------|-----------|
| **PV** | Solar panels (DC side) | `PVMetadata` | `PVTelemetry` |
| **Inverter** | AC conversion point | `InverterMetadata` | `InverterTelemetry` |
| **Battery** | Energy storage | `BatteryMetadata` | `BatteryTelemetry` |
| **Meter** | Grid connection point | `MeterMetadata` | `MeterTelemetry` |
| **V2X Charger** | Bidirectional EV charger | `V2XChargerMetadata` | `V2XChargerTelemetry` |
## Sign Convention
| DER Type | Positive W (+) | Negative W (-) |
|----------|----------------|----------------|
| **PV** | n/a | Generation/export |
| **Battery** | Charging (import) | Discharging (export) |
| **Meter** | Import from grid | Export to grid |
| **V2X** | Charging EV (import) | V2G discharge (export) |
## Complete Models
Each DER type has a complete model combining metadata (spec) and telemetry (state):
```typescript
import { PVModel, BatteryModel } from '@srcful/data-models';
const pv: PVModel = {
type: 'pv',
device_sn: 'SG123456',
spec: { /* PVMetadata */ },
state: { /* PVTelemetry */ },
};
```
## Development
```bash
# Install dependencies
npm install
# Run playground with example data
npm run playground
# Type check
npm run typecheck
# Build
npm run build
```
## Documentation
See [device_metadata.md](./device_metadata.md) for the complete architecture documentation.
## License
MIT