Skip to content

Commit 4e1df08

Browse files
author
BESS Solutions
committed
docs(standard): Global Standard Foundations v1.8.0 — 21 files
Eje 2 — Formal Specifications: - docs/specs/BESSAI-SPEC-001.md — BESSDriver Interface (RFC 2119, IEC 61850) - docs/specs/BESSAI-SPEC-002.md — Safety Requirements (IEC 62619, IEC 62443) - docs/specs/BESSAI-SPEC-003.md — Telemetry Schema (JSON Schema 2020-12) - docs/adr/0007-json-schema-telemetry-specification.md - docs/adr/0008-bep-process-for-specification-changes.md Eje 5 — Open Governance: - docs/bep/BEP-0001.md — Meta-BEP process definition - GOVERNANCE.md — TSC (>=40% external) + BEP process - .github/DISCUSSION_TEMPLATE/bep_discussion.yml - .github/DISCUSSION_TEMPLATE/adopter_introduction.yml Eje 4 — Interoperability: - docs/interoperability/interop_test_suite.md - docs/interoperability/BESSAI-CERTIFIED.md - tests/interop/test_driver_contract.py - registry/TEMPLATE_interop_certification.json Eje 6 — Public Benchmarks: - docs/benchmarks/BENCHMARK-001/002/003-*.md - scripts/run_benchmarks.py - .github/workflows/benchmark.yml Eje 3 — Certification: - docs/compliance/iec_62443_sl2_certification_path.md - docs/compliance/ieee_2030_5_compliance.md - .github/workflows/compliance-report.yml Eje 1 — Adoption: - docs/adopters.md - docs/partnership_program.md - docs/lf_energy_proposal.md Modified: README.md, GOVERNANCE.md, mkdocs.yml, CHANGELOG.md, PROJECT_STATUS.md Tests: 378/378 passed
1 parent ed4430a commit 4e1df08

28 files changed

Lines changed: 3423 additions & 42 deletions

‎.github/DISCUSSION_TEMPLATE/adopter_introduction.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
title: "Adopter Introduction"
2+
description: "Introduce your organization as a user or integrator of BESSAI Edge Gateway. Join the community of adopters!"
3+
labels: ["adopter", "community"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
## Welcome to the BESSAI community! 🎉
9+
If your organization is using, deploying, or building on BESSAI Edge Gateway, we'd love to hear from you. Adopter introductions help us understand real-world use cases and prioritize the roadmap.
10+
11+
Your organization can also be listed in [`docs/adopters.md`](../docs/adopters.md) — just mention it below and open a PR!
12+
13+
- type: input
14+
id: organization
15+
attributes:
16+
label: Organization name
17+
placeholder: "e.g., Energía Renovable S.A."
18+
validations:
19+
required: true
20+
21+
- type: input
22+
id: country
23+
attributes:
24+
label: Country / Region
25+
placeholder: "e.g., Chile, Germany, Australia"
26+
validations:
27+
required: true
28+
29+
- type: dropdown
30+
id: adopter_tier
31+
attributes:
32+
label: How are you using BESSAI?
33+
options:
34+
- "🔌 Integrator — deploying BESSAI in customer projects"
35+
- "🏭 Operator — running BESSAI at our own sites"
36+
- "🔬 Research — using BESSAI for academic or R&D purposes"
37+
- "🤝 Contributor — contributing code, drivers, or documentation"
38+
- "👀 Evaluating — assessing BESSAI for future use"
39+
validations:
40+
required: true
41+
42+
- type: dropdown
43+
id: hardware
44+
attributes:
45+
label: Hardware you are connecting with
46+
multiple: true
47+
options:
48+
- "Huawei SUN2000"
49+
- "SMA Sunny Tripower"
50+
- "Victron MultiPlus-II"
51+
- "Fronius GEN24"
52+
- "Other (describe below)"
53+
validations:
54+
required: false
55+
56+
- type: textarea
57+
id: use_case
58+
attributes:
59+
label: Your use case
60+
description: Brief description of your deployment or project. No confidential details needed.
61+
placeholder: "We are using BESSAI to manage a 500 kWh LFP installation at a solar farm in the Atacama region, integrating with our existing SCADA system via MQTT..."
62+
63+
- type: textarea
64+
id: feedback
65+
attributes:
66+
label: Feedback or feature requests
67+
description: What would make BESSAI work better for your use case?
68+
69+
- type: checkboxes
70+
id: listing
71+
attributes:
72+
label: Adopter listing
73+
options:
74+
- label: "I consent to my organization being listed in `docs/adopters.md` (you can open a PR or we can add it)"
75+
- label: I would be interested in joining the Technical Steering Committee (TSC) as an external member
76+
77+
- type: input
78+
id: contact
79+
attributes:
80+
label: Contact (optional)
81+
description: GitHub handle, email, or LinkedIn — only share what you are comfortable making public
82+
placeholder: "@github-handle or contact@example.com"

‎.github/DISCUSSION_TEMPLATE/bep_discussion.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
title: "BEP Pre-Discussion"
2+
description: "Start a discussion before writing a formal BEP. Early feedback helps determine if a BEP is the right vehicle and shapes the proposal."
3+
labels: ["bep", "discussion"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
## Before you open this discussion
9+
A BEP (BESSAI Enhancement Proposal) is required only for changes that affect:
10+
- BESSAI-SPEC-* specifications (driver interface, safety requirements, telemetry schema)
11+
- GOVERNANCE.md or the BEP process itself
12+
- Architectural changes that break compatibility for external adopters
13+
14+
**For bug fixes, new device drivers, or non-breaking features, open a PR directly.**
15+
16+
- type: input
17+
id: title
18+
attributes:
19+
label: Proposal title
20+
placeholder: "e.g., Add SoH% as a required tag in BESSAI-SPEC-001"
21+
validations:
22+
required: true
23+
24+
- type: dropdown
25+
id: bep_type
26+
attributes:
27+
label: Expected BEP type
28+
options:
29+
- "Standards Track (changes to BESSAI-SPEC-*)"
30+
- "Governance (changes to GOVERNANCE.md or BEP process)"
31+
- "Informational (significant observation, no normative changes)"
32+
validations:
33+
required: true
34+
35+
- type: textarea
36+
id: problem
37+
attributes:
38+
label: Problem statement
39+
description: What problem are you trying to solve? Why does it need a formal specification change?
40+
placeholder: "Currently, conforming drivers are not required to report State of Health. This means the SafetyGuard cannot account for degraded batteries..."
41+
validations:
42+
required: true
43+
44+
- type: textarea
45+
id: proposed_solution
46+
attributes:
47+
label: Proposed solution (sketch)
48+
description: A rough outline of your proposed change. This will evolve into the BEP specification section.
49+
placeholder: "Add SoH_% as a RECOMMENDED tag in BESSAI-SPEC-001 §5.3, with a MUST requirement for all drivers that support the tag to return a value in [0, 100]..."
50+
validations:
51+
required: true
52+
53+
- type: textarea
54+
id: alternatives
55+
attributes:
56+
label: Alternatives considered
57+
description: What else did you consider? This helps the community understand your reasoning.
58+
59+
- type: checkboxes
60+
id: checklist
61+
attributes:
62+
label: Pre-discussion checklist
63+
options:
64+
- label: I have searched existing BEPs and GitHub Discussions for similar proposals
65+
required: true
66+
- label: I believe this change requires a formal BEP (not just a PR)
67+
required: true

‎.github/workflows/benchmark.yml‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
name: "Weekly Benchmarks"
2+
3+
on:
4+
schedule:
5+
- cron: "0 6 * * 1" # Every Monday at 06:00 UTC
6+
workflow_dispatch: # Allow manual trigger
7+
8+
permissions:
9+
contents: read
10+
issues: write # Needed to open issues on threshold breach
11+
12+
jobs:
13+
benchmark-latency:
14+
name: "Benchmark 001 — Gateway Cycle Latency"
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python 3.11
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: "3.11"
23+
cache: pip
24+
25+
- name: Install dependencies
26+
run: |
27+
pip install --upgrade pip
28+
pip install -r requirements.txt -r requirements-dev.txt
29+
30+
- name: Run latency benchmark (100 cycles, CI mode)
31+
run: |
32+
python scripts/run_benchmarks.py --benchmark 001 --cycles 100 --ci \
33+
--output benchmark_001_results.json
34+
35+
- name: Upload benchmark results
36+
uses: actions/upload-artifact@v4
37+
with:
38+
name: benchmark-001-latency-${{ github.run_id }}
39+
path: benchmark_001_results.json
40+
41+
- name: Check thresholds and alert
42+
run: |
43+
python - <<'EOF'
44+
import json, sys
45+
46+
with open("benchmark_001_results.json") as f:
47+
results = json.load(f)
48+
49+
cycle_p99_ms = results.get("cycle_total_p99_ms", 0)
50+
onnx_p99_ms = results.get("onnx_inference_p99_ms", 0)
51+
safety_p99_ms = results.get("safety_eval_p99_ms", 0)
52+
53+
alerts = []
54+
if cycle_p99_ms > 4800:
55+
alerts.append(f"❌ cycle_total P99 = {cycle_p99_ms:.1f}ms > 4800ms threshold")
56+
if onnx_p99_ms > 100:
57+
alerts.append(f"❌ onnx_inference P99 = {onnx_p99_ms:.1f}ms > 100ms threshold")
58+
if safety_p99_ms > 500:
59+
alerts.append(f"❌ safety_eval P99 = {safety_p99_ms:.1f}ms > 500ms threshold")
60+
61+
if alerts:
62+
print("BENCHMARK THRESHOLD EXCEEDED:")
63+
for a in alerts:
64+
print(a)
65+
print(f"\ncycle_total P99: {cycle_p99_ms:.1f}ms")
66+
print(f"onnx P99: {onnx_p99_ms:.1f}ms")
67+
print(f"safety P99: {safety_p99_ms:.1f}ms")
68+
sys.exit(1)
69+
else:
70+
print("✅ All benchmark thresholds within limits")
71+
print(f" cycle_total P99: {cycle_p99_ms:.1f}ms (< 4800ms)")
72+
print(f" onnx_inference P99:{onnx_p99_ms:.1f}ms (< 100ms)")
73+
print(f" safety_eval P99: {safety_p99_ms:.1f}ms (< 500ms)")
74+
EOF
75+
76+
benchmark-scale:
77+
name: "Benchmark 002 — Fleet Scalability"
78+
runs-on: ubuntu-latest
79+
steps:
80+
- uses: actions/checkout@v4
81+
82+
- name: Set up Python 3.11
83+
uses: actions/setup-python@v5
84+
with:
85+
python-version: "3.11"
86+
cache: pip
87+
88+
- name: Install dependencies
89+
run: |
90+
pip install --upgrade pip
91+
pip install -r requirements.txt -r requirements-dev.txt
92+
93+
- name: Run scalability benchmark (up to 50 sites)
94+
run: |
95+
python scripts/run_benchmarks.py --benchmark 002 --max-sites 50 --ci \
96+
--output benchmark_002_results.json
97+
98+
- name: Upload benchmark results
99+
uses: actions/upload-artifact@v4
100+
with:
101+
name: benchmark-002-scale-${{ github.run_id }}
102+
path: benchmark_002_results.json
103+
104+
- name: Check scalability thresholds
105+
run: |
106+
python - <<'EOF'
107+
import json, sys
108+
109+
with open("benchmark_002_results.json") as f:
110+
results = json.load(f)
111+
112+
# Check 10-site cycle P99
113+
p99_at_10 = results.get("sites_10_cycle_p99_ms", 0)
114+
p99_at_50 = results.get("sites_50_cycle_p99_ms", 0)
115+
116+
alerts = []
117+
if p99_at_10 > 30:
118+
alerts.append(f"❌ 10-site cycle P99 = {p99_at_10:.1f}ms > 30ms threshold")
119+
if p99_at_50 > 5000:
120+
alerts.append(f"❌ 50-site cycle P99 = {p99_at_50:.1f}ms > 5000ms threshold")
121+
122+
if alerts:
123+
for a in alerts:
124+
print(a)
125+
sys.exit(1)
126+
else:
127+
print("✅ Fleet scalability within limits")
128+
print(f" 10-site P99: {p99_at_10:.1f}ms (< 30ms)")
129+
print(f" 50-site P99: {p99_at_50:.1f}ms (< 5000ms)")
130+
EOF
131+
132+
interop-contract-tests:
133+
name: "Interop — Driver Contract Tests (SimulatorDriver)"
134+
runs-on: ubuntu-latest
135+
steps:
136+
- uses: actions/checkout@v4
137+
138+
- name: Set up Python 3.11
139+
uses: actions/setup-python@v5
140+
with:
141+
python-version: "3.11"
142+
cache: pip
143+
144+
- name: Install dependencies
145+
run: |
146+
pip install --upgrade pip
147+
pip install -r requirements.txt -r requirements-dev.txt
148+
149+
- name: Run driver contract tests (Category A — no hardware)
150+
run: |
151+
pytest tests/interop/test_driver_contract.py::TestContract \
152+
-v --tb=short --junit-xml=interop_contract_results.xml
153+
154+
- name: Upload contract test results
155+
uses: actions/upload-artifact@v4
156+
with:
157+
name: interop-contract-results-${{ github.run_id }}
158+
path: interop_contract_results.xml

0 commit comments

Comments
 (0)