|
| 1 | +--- |
| 2 | +sidebar_position: 1 |
| 3 | +slug: /developer/core_principles |
| 4 | +pagination_prev: null |
| 5 | +--- |
| 6 | + |
| 7 | +# Core Principles |
| 8 | + |
| 9 | +The Sourceful energy system is built on fundamental principles that ensure data integrity, energy conservation, and system reliability. These principles are foundational and constitutional - they govern all modeling, control, and accounting operations within the Sourceful ecosystem. |
| 10 | + |
| 11 | +## Table of Contents |
| 12 | + |
| 13 | +- [Foundational Principles](#foundational-principles) |
| 14 | + - [1. Energy is Primary](#1-energy-is-primary) |
| 15 | + - [2. The Site Boundary](#2-the-site-boundary) |
| 16 | + - [3. Canonical Sign Convention](#3-canonical-sign-convention) |
| 17 | + - [4. Units and Base System](#4-units-and-base-system) |
| 18 | + - [5. Determinism](#5-determinism) |
| 19 | + - [6. The Source of Time](#6-the-source-of-time) |
| 20 | + - [7. Simplicity & Extensibility](#7-simplicity--extensibility) |
| 21 | +- [Conservation Example](#conservation-example) |
| 22 | + |
| 23 | +## Foundational Principles |
| 24 | + |
| 25 | +### 1. Energy is Primary |
| 26 | + |
| 27 | +All modeling, control, and accounting start with energy. Power is always derived as ΔE/Δt. This hierarchy is never reversed. |
| 28 | + |
| 29 | +### 2. The Site Boundary |
| 30 | + |
| 31 | +Every calculation is framed relative to a clearly defined Site. |
| 32 | + |
| 33 | +The Site is the thermodynamic control volume and, by default, the Point of Common Coupling (PCC) at the utility revenue/grid interconnection meter. All imports, exports, on-site generation, and storage are measured relative to this point. |
| 34 | + |
| 35 | +If there are multiple service entrances, a single designated virtual Site must be declared, and all contributing meters explicitly mapped to it. |
| 36 | + |
| 37 | +### 3. Canonical Sign Convention |
| 38 | + |
| 39 | +- **Positive = flow into the Site** |
| 40 | +- **Negative = flow out of the Site** |
| 41 | + |
| 42 | +This rule applies universally across telemetry, metrics, storage, and control. Counters are always positive and monotonic, but are split into import and export streams. |
| 43 | + |
| 44 | +### 4. Units and Base System |
| 45 | + |
| 46 | +Internal representation uses only base SI units: watts (W), watt-hours (Wh), volts (V), amps (A), hertz (Hz), degrees Celsius (°C), and time as Unix ms or ISO-8601. Unit conversions are performed only at ingestion or egress boundaries. |
| 47 | + |
| 48 | +### 5. Determinism |
| 49 | + |
| 50 | +Physics must be conserved in every layer. The signed sum of all power (or interval energies) at the Site must balance within ε. Any violation is a fault, not "just noise." |
| 51 | + |
| 52 | +### 6. The Source of Time |
| 53 | + |
| 54 | +Time is stamped at the first Sourceful-controlled collection point. This is the temporal authority for all measurements. |
| 55 | + |
| 56 | +**The Sourceful Time Rule:** |
| 57 | +Timestamps are applied by our gateways at the moment of data ingestion. We explicitly do NOT trust device clocks from inverters, meters, or third-party hardware. The first Sourceful software that touches the data owns the timestamp. |
| 58 | + |
| 59 | +**Gateway Time Requirements:** |
| 60 | +- All Sourceful gateways must maintain NTP synchronization to a common time source |
| 61 | +- Maximum acceptable drift: ±100ms between any two gateways at a Site |
| 62 | +- Timestamps applied as Unix epoch milliseconds in UTC |
| 63 | +- Gateway health includes NTP sync status and last sync time |
| 64 | + |
| 65 | +**The Collection Moment:** |
| 66 | +When a gateway reads a register (Modbus), receives a message (MQTT), or polls an API, it immediately stamps that measurement with its synchronized clock. This timestamp travels with the data forever - it is immutable and represents when Sourceful first observed the value. |
| 67 | + |
| 68 | +**Example:** |
| 69 | +An inverter reports 5247W but has a clock that's 3 hours off. Zap polls this inverter at 2024-01-15T14:30:00.000Z. The recorded measurement is: |
| 70 | + |
| 71 | +```json |
| 72 | +{ |
| 73 | + "power_W": 5247, |
| 74 | + "timestamp": 1705330200000, |
| 75 | + "gateway": "zap-0342", |
| 76 | + "source": "inverter-01" |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +The SOURCE of time is Sourceful. Physics determines the values; we determine when we saw them. |
| 81 | + |
| 82 | +### 7. Simplicity & Extensibility |
| 83 | + |
| 84 | +The Core changes rarely and only with consensus. All extensions—such as IEEE mappings, schemas, metric rules, and gateway tier strategies—must conform to this document. The purpose of the Core is to set boundaries and invariants, not to prescribe implementation detail. |
| 85 | + |
| 86 | +## Conservation Example |
| 87 | + |
| 88 | +### Energy Balance at the PCC |
| 89 | + |
| 90 | +The *Point of Common Coupling (PCC)* — the utility grid meter — is the **gate of the Site**. All energy must pass through this gate. The energy balance is written as: |
| 91 | + |
| 92 | +``` |
| 93 | +ΔE(PCC) = LOAD + PV + BATT + EV + … |
| 94 | +``` |
| 95 | + |
| 96 | +Every term is always **added with a plus sign**. The **sign of the value** encodes direction: |
| 97 | + |
| 98 | +- **Positive (+)** → energy flowing into the Site (import, consumption, charging) |
| 99 | +- **Negative (–)** → energy flowing out of the Site (export, generation, discharging) |
| 100 | + |
| 101 | +**Examples:** |
| 102 | + |
| 103 | +- Grid importing 3 kWh → `ΔE(PCC) = +3000 Wh` |
| 104 | +- Grid exporting 2 kWh → `ΔE(PCC) = –2000 Wh` |
| 105 | +- PV generation of 5 kWh → recorded as `–5000 Wh` (flow out of Site) |
| 106 | +- Battery charging with 2 kWh → recorded as `+2000 Wh` (flow into Site) |
| 107 | + |
| 108 | +The math is always a sum. Engineers don't need to remember which channels are "subtracted"; the rule is universal: direction is in the sign. |
| 109 | + |
| 110 | +This formulation is not arbitrary; it is **energy conservation** applied at the Site boundary. The Site is treated as a **thermodynamic control volume**: |
| 111 | + |
| 112 | +$$ |
| 113 | +\Delta E_\text{PCC} = \sum_i \Delta E_i |
| 114 | +$$ |
| 115 | + |
| 116 | +The equation says: whatever crosses into or out of the Site must add up. Energy cannot vanish; it only changes form or direction. By always summing with plus signs and encoding direction in the sign of each term, we are directly enforcing conservation of energy in software. |
| 117 | + |
| 118 | +Any mismatch beyond tolerance ε means something is broken — a meter error, telemetry bug, or mis-signed flow. This is how physics itself becomes a validator for the system. |
0 commit comments