Skip to content

Commit b9468bc

Browse files
scottrfrancisclaude
andcommitted
docs: Add CHANGELOG.md for v0.1.3-alpha release
Comprehensive release notes covering: - Critical production deployment fixes (PR #10) - Major documentation improvements (PR #9) - NPU/model_zoo compatibility (PR #8) Key changes: - Fix read-only filesystem errors - Fix user script execution on noexec - Add QUICKSTART, WORKFLOWS, FAQ guides - Enable rknn_model_zoo with RKNNLite Breaking: Requires OS 9.1.79.3+ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent bd187d6 commit b9468bc

File tree

1 file changed

+183
-0
lines changed

1 file changed

+183
-0
lines changed

CHANGELOG.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Changelog
2+
3+
All notable changes to the BrightSign Python Extension for CV Development will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.3-alpha] - 2025-10-22
9+
10+
### Critical Fixes
11+
12+
#### Production Deployment Issues (PR #10)
13+
- **Fixed**: Read-only filesystem errors preventing production extension startup
14+
- Removed obsolete lib64 workaround code (42% code reduction in RKNN setup)
15+
- Extension now uses OS-provided librknnrt.so directly (OS 9.1.79.3+)
16+
- No filesystem operations in extension code (100% compatible with read-only squashfs)
17+
- **Fixed**: User scripts not executing on noexec filesystems
18+
- Changed detection logic from `-x` (executable) to `-r` (readable) test
19+
- All `.sh` files in `/storage/sd/python-init/` now run automatically
20+
- Documented noexec filesystem behavior and proper disable methods
21+
- **Fixed**: Package installation errors in user-init examples
22+
- Updated test_cv_packages.py to use rknnlite (not obsolete rknn)
23+
- Removed pre-installed SDK packages from requirements.txt template
24+
- Made validation script informational (always succeeds, reports availability)
25+
26+
**Customer Impact**: Production deployments now work correctly on BrightSign players with user scripts executing as expected.
27+
28+
### Added
29+
30+
#### Documentation Suite (PR #9)
31+
- **QUICKSTART.md**: 60-90 minute quick start guide for new users
32+
- 3-command build process with clear time expectations
33+
- Common issues and immediate fixes
34+
- Complete NPU example walkthrough
35+
- **WORKFLOWS.md**: Copy-paste command reference for common tasks
36+
- First-time setup, rebuild workflows, deployment procedures
37+
- NPU testing, user init scripts, troubleshooting commands
38+
- **FAQ.md**: 25+ frequently asked questions with detailed answers
39+
- Architecture compatibility (Apple Silicon workarounds)
40+
- Build optimization, package types, firmware updates
41+
- NPU requirements, installation procedures
42+
- **check-prerequisites**: System validation script
43+
- Validates x86_64 architecture (fails fast on Apple Silicon)
44+
- Checks Docker, disk space (50GB+), memory (16GB+)
45+
- Verifies internet connectivity and required tools
46+
- **docs/getting-started.md**: Complete first-time setup guide
47+
- **docs/deployment.md**: Comprehensive deployment procedures
48+
- **docs/model-zoo-guide.md**: NPU usage with 50+ pre-trained models
49+
- **docs/troubleshooting-user-init.md**: 21+ failure point diagnostics
50+
51+
#### NPU/Model Zoo Support (PR #8)
52+
- **Added**: RKNNLite compatibility layer for rknn_model_zoo examples
53+
- Enables official model_zoo examples to run on BrightSign
54+
- Patched py_utils with RKNNLite adapter (full toolkit incompatible)
55+
- Validated YOLOX object detection (93% accuracy on bus.jpg)
56+
- **Added**: Complete py_utils compatibility wrapper in user-init/examples/
57+
- rknn_executor.py with API adaptations
58+
- coco_utils.py, onnx_executor.py, pytorch_executor.py
59+
- __init__.py package marker
60+
- **Added**: Comprehensive session logs documenting technical decisions
61+
- OS 9.1.79.3 resolution breakthrough
62+
- Model zoo compatibility implementation
63+
- Production deployment fixes
64+
65+
### Changed
66+
67+
#### Documentation Restructure (PR #9)
68+
- **README.md**: Complete rewrite with progressive disclosure
69+
- Reduced from 1270 lines to 456 lines (64% reduction)
70+
- Added visual ASCII architecture diagram
71+
- Feature highlights with code examples
72+
- Quick reference troubleshooting table
73+
- Links to detailed guides instead of inline detail
74+
- **Enhanced Scripts**: build and setup scripts with rich progress indicators
75+
- Visual progress with Unicode box drawing
76+
- Time estimates (30-60min SDK, 5-15min packages)
77+
- Context-aware next steps suggestions
78+
- Enhanced error messages with immediate solutions
79+
80+
#### Package Architecture (PR #8)
81+
- **Changed**: RKNNLite-only approach (removed incompatible full rknn-toolkit2)
82+
- Full toolkit has hardcoded /usr/lib64/ paths (x86_64-specific)
83+
- RKNNLite designed for ARM64 embedded targets
84+
- Reduced package complexity while maintaining functionality
85+
- **Changed**: User-init examples updated to match SDK architecture
86+
- Test script validates actual SDK contents (18/20 packages)
87+
- Requirements template shows only user-installable packages
88+
- Clear documentation of pre-installed vs user packages
89+
90+
### Fixed
91+
92+
#### Core Stability
93+
- Extension initialization on production deployments (read-only filesystem)
94+
- User script execution on noexec mounts (/storage/sd)
95+
- Package installation errors from SDK/user package conflicts
96+
- RKNN model_zoo example compatibility (RKNNLite adapter)
97+
98+
#### Documentation
99+
- Inconsistent installation instructions
100+
- Missing troubleshooting for common deployment issues
101+
- Unclear prerequisites and compatibility requirements
102+
- Time expectations for build process
103+
104+
### Documentation
105+
106+
- Added 6+ comprehensive guides covering setup, deployment, NPU usage
107+
- Enhanced README with visual architecture diagram and progressive disclosure
108+
- Created troubleshooting guide with 21+ diagnostic procedures
109+
- Added session logs documenting technical decisions and validation
110+
- Improved inline script documentation with progress indicators
111+
112+
### Breaking Changes
113+
114+
- **Requires BrightSign OS 9.1.79.3+**: Earlier versions lack /usr/lib/librknnrt.so
115+
- Extension uses OS-provided RKNN runtime library
116+
- All workarounds for older OS versions removed
117+
- Update player firmware before deploying this version
118+
119+
### Migration Guide
120+
121+
**From v0.1.2-alpha**:
122+
1. Ensure BrightSign players are running OS 9.1.79.3 or later
123+
2. Rebuild extension: `./build --extract-sdk && ./package`
124+
3. Deploy production package: `ext_pydev-YYYYMMDD-HHMMSS.zip`
125+
4. User scripts in `/storage/sd/python-init/` now run automatically
126+
5. Update any custom scripts using `from rknn.api import RKNN` to use `from rknnlite.api import RKNNLite`
127+
128+
### Known Issues
129+
130+
- Minor package warnings (pandas, scikit-image) due to NumPy ABI mismatch (non-blocking)
131+
- Apple Silicon requires x86_64 cloud VM or Docker emulation (significant performance penalty)
132+
- Build requires 50GB+ disk space and 30-60 minutes on first run
133+
134+
### Validation Results
135+
136+
- ✅ Production deployment tested on BrightSign XT-5 with OS 9.1.79.3
137+
- ✅ User scripts execute correctly from /storage/sd/python-init/
138+
- ✅ RKNN model_zoo YOLOX example: 93% detection confidence
139+
- ✅ Core CV/ML packages validated: OpenCV 4.5.5, PyTorch 2.4.1, RKNNLite
140+
- ✅ 18/20 test packages available (2 informational warnings)
141+
142+
### Contributors
143+
144+
- Scott Francis <scott.russell.francis@gmail.com>
145+
- Claude (AI pair programming assistant)
146+
147+
---
148+
149+
## [0.1.2-alpha] - 2025-01-31
150+
151+
### Added
152+
- OS 9.1.79.3 support with native librknnrt.so
153+
- Automatic RKNN library detection and configuration
154+
- NPU inference validation with YOLOX model
155+
156+
### Changed
157+
- Removed 460+ lines of binary patching workarounds
158+
- Simplified RKNN library setup (uses OS-provided library)
159+
160+
### Fixed
161+
- RKNN initialization on BrightSign OS 9.1.79.3+
162+
- Library path resolution for ARM64 architecture
163+
164+
---
165+
166+
## [0.1.1-alpha] - 2025-01-28
167+
168+
### Added
169+
- Initial alpha release
170+
- Python 3.8 cross-compilation for ARM64
171+
- OpenCV, PyTorch, RKNN toolkit integration
172+
- Comprehensive package gap analysis
173+
- Docker-based build environment
174+
175+
### Known Issues
176+
- RKNN library path issues (resolved in 0.1.2-alpha)
177+
- Requires complex binary patching (resolved in 0.1.2-alpha)
178+
179+
---
180+
181+
[0.1.3-alpha]: https://github.com/brightsign/python-cv-dev-extension/compare/v0.1.2-alpha...v0.1.3-alpha
182+
[0.1.2-alpha]: https://github.com/brightsign/python-cv-dev-extension/compare/v0.1.1-alpha...v0.1.2-alpha
183+
[0.1.1-alpha]: https://github.com/brightsign/python-cv-dev-extension/releases/tag/v0.1.1-alpha

0 commit comments

Comments
 (0)