{"id":30805525,"url":"https://github.com/aaronsb/rec-bmsmanagement","last_synced_at":"2025-09-06T00:58:45.408Z","repository":{"id":310548513,"uuid":"1040291722","full_name":"aaronsb/REC-BMSManagement","owner":"aaronsb","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-18T20:16:27.000Z","size":4650,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-18T20:42:27.747Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-18T18:44:44.000Z","updated_at":"2025-08-18T20:16:30.000Z","dependencies_parsed_at":"2025-08-18T20:52:41.784Z","dependency_job_id":null,"html_url":"https://github.com/aaronsb/REC-BMSManagement","commit_stats":null,"previous_names":["aaronsb/rec-bmsmanagement"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/REC-BMSManagement","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2FREC-BMSManagement","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2FREC-BMSManagement/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2FREC-BMSManagement/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2FREC-BMSManagement/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/REC-BMSManagement/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2FREC-BMSManagement/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842830,"owners_count":25177921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T00:58:41.938Z","updated_at":"2025-09-06T00:58:45.387Z","avatar_url":"https://github.com/aaronsb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Open REC 1Q Firmware\r\n\r\nAn open-source Battery Management System implementation for REC BMS 1Q hardware, featuring a Python management interface and efficient C++ firmware replacement for the AT90CAN32 microcontroller.\r\n\r\n## ⛔ CRITICAL WARNING - READ BEFORE USE ⛔\r\n\r\n**Installing Open REC 1Q Firmware will:**\r\n- **VOID ALL WARRANTIES** from REC BMS permanently\r\n- **ELIMINATE ALL SUPPORT** from REC BMS\r\n- **POTENTIALLY BRICK YOUR DEVICE** requiring ISP programmer recovery\r\n- **RISK BATTERY DAMAGE OR FIRE** if misconfigured\r\n\r\n**This is THIRD-PARTY SOFTWARE not affiliated with REC BMS. Use at your own risk!**\r\n\r\nSee [LICENSE](LICENSE) for full disclaimers and warnings.\r\n\r\n## 🎯 Project Overview\r\n\r\nThe **Open REC 1Q Firmware** project provides:\r\n- **Python Library**: High-level BMS control and monitoring via RS485\r\n- **C++ Firmware**: Clean, efficient replacement for LabVIEW-generated code  \r\n- **Complete Documentation**: Protocol specifications, hardware pinouts, algorithms\r\n- **Development Tools**: Disassembly, analysis, and programming utilities\r\n\r\n### Why Open REC 1Q Firmware?\r\n\r\nThe original REC BMS firmware was generated using LabVIEW, resulting in:\r\n- 93% flash usage (30KB of 32KB)\r\n- Inefficient code structure\r\n- Limited expandability\r\n- Poor maintainability\r\n\r\nOur open-source C++ implementation provides:\r\n- **40% flash usage** (13KB of 32KB)\r\n- **Clean, maintainable code**\r\n- **Room for additional features**\r\n- **3x faster execution**\r\n- **Community-driven development**\r\n\r\n## 📚 Documentation\r\n\r\n### Core Documentation\r\n- [**Firmware Analysis Report**](docs/FIRMWARE_ANALYSIS.md) - Comprehensive analysis of the original firmware\r\n- [**System Architecture**](docs/architecture.md) - Overall system design and data flow\r\n- [**State Machine**](docs/state-machine.md) - BMS operational states and transitions\r\n- [**Communication Protocols**](docs/protocols.md) - Complete RS485 and CAN message specifications\r\n- [**MCU Pinout**](docs/pinout.md) - AT90CAN32 pin configuration and board layout\r\n- [**Cell Management Algorithm**](docs/CELL_MANAGEMENT_ALGORITHM.md) - Battery management logic\r\n\r\n### API Documentation\r\n- [**Python API**](docs/python-api.md) - Python library usage and examples\r\n- [**Firmware API**](docs/firmware-api.md) - C++ firmware functions and structures\r\n\r\n### Development Guides\r\n- [**Firmware Recreation Plan**](docs/FIRMWARE_RECREATION_PLAN.md) - Reverse engineering approach\r\n- [**Project Plan**](docs/PROJECT_PLAN.md) - Development roadmap\r\n- [**Baud Rate Guide**](docs/BAUD_RATE_GUIDE.md) - Custom baud rate configuration\r\n\r\n### Reference Materials\r\n- [PDF Documentation](docs/pdfs/) - REC BMS manuals and datasheets\r\n- [Firmware Resources](resources/firmware/) - Original firmware and binaries\r\n- [Disassembly Tools](resources/disassembly/) - Analysis scripts and tools\r\n\r\n## 🚀 Quick Start\r\n\r\n### Python Interface\r\n\r\n```bash\r\n# Install Python package\r\ncd rec_bms_manager\r\npip install -e .\r\n\r\n# Test connection\r\nrec-bms auto-detect\r\n\r\n# Monitor battery\r\nrec-bms monitor -p /dev/ttyUSB0 -b 56000\r\n```\r\n\r\n```python\r\nfrom rec_bms_manager import BMSManager\r\n\r\n# Connect to BMS\r\nbms = BMSManager(port='/dev/ttyUSB0', baud_rate=56000)\r\nbms.connect()\r\n\r\n# Get battery status\r\nstatus = bms.get_status()\r\nprint(f\"Voltage: {status['voltage']}V\")\r\nprint(f\"SOC: {status['soc']}%\")\r\n```\r\n\r\n### Firmware Programming\r\n\r\n```bash\r\n# Build firmware\r\ncd firmware\r\nmake clean \u0026\u0026 make\r\n\r\n# Program via ISP (Con4 header)\r\n./program_isp.sh\r\n```\r\n\r\n## 🏗️ Project Structure\r\n\r\n```\r\nREC-BMSManagement/\r\n├── firmware/                 # Open REC 1Q C++ firmware\r\n│   ├── include/             # Header files\r\n│   ├── src/                 # Source files\r\n│   ├── Makefile            # Build configuration\r\n│   └── program_isp.sh      # ISP programming script\r\n│\r\n├── rec_bms_manager/         # Python management interface\r\n│   ├── core/               # Core BMS communication\r\n│   ├── utils/              # Utility functions\r\n│   └── cli.py             # Command-line interface\r\n│\r\n├── docs/                    # Documentation\r\n│   ├── architecture.md     # System design\r\n│   ├── protocols.md        # Protocol specs\r\n│   ├── pinout.md          # Hardware pinouts\r\n│   └── pdfs/              # Reference manuals\r\n│\r\n├── resources/               # Development resources\r\n│   ├── firmware/           # Original firmware files\r\n│   └── disassembly/        # Analysis tools\r\n│\r\n└── examples/                # Usage examples\r\n```\r\n\r\n## 🏆 Features\r\n\r\n### Battery Management\r\n- ✅ 16-cell lithium battery support (5-16 cells configurable)\r\n- ✅ Individual cell voltage monitoring via dual MAX14752 analog multiplexers + 10-bit internal ADC\r\n- ✅ Temperature monitoring via Dallas DS18B20 (up to 4 sensors)\r\n- ✅ Current monitoring (shunt resistor, 18-bit ADC)\r\n- ✅ Passive cell balancing (4.3Ω resistors, up to 900mA per cell)\r\n- ✅ SOC/SOH calculation\r\n- ✅ Multi-level protection (OV/UV/OC/OT/UT)\r\n\r\n### Communication\r\n- ✅ RS485 interface (38400/56000 baud)\r\n- ✅ CAN bus (Victron Energy protocol)\r\n- ✅ Bootloader support via RS485\r\n- ✅ ISP programming via Con4 header\r\n\r\n### Open Source Benefits\r\n- ✅ Community-driven development\r\n- ✅ Transparent implementation\r\n- ✅ Customizable for specific needs\r\n- ✅ No vendor lock-in\r\n- ✅ Educational resource\r\n\r\n## 🔧 Hardware Compatibility\r\n\r\n### Supported Hardware\r\n- **REC BMS 1Q** with AT90CAN32 microcontroller\r\n- Compatible with all REC 1Q variants (4-16 cells)\r\n- Works with existing REC BMS wiring and sensors\r\n\r\n### Required Tools\r\n- ISP programmer (USBasp, AVR ISP mkII, etc.)\r\n- USB-to-RS485 adapter (FTDI recommended)\r\n- Optional: CAN interface for monitoring\r\n\r\n## 📦 Installation\r\n\r\n### Prerequisites\r\n\r\n```bash\r\n# AVR Toolchain (choose your platform)\r\n\r\n# Arch Linux\r\nsudo pacman -S avr-gcc avr-libc avrdude\r\n\r\n# Ubuntu/Debian  \r\nsudo apt-get install gcc-avr avr-libc avrdude\r\n\r\n# macOS\r\nbrew tap osx-cross/avr\r\nbrew install avr-gcc avrdude\r\n```\r\n\r\n### Clone and Build\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/aaronsb/REC-BMSManagement.git\r\ncd REC-BMSManagement\r\n\r\n# Build firmware\r\ncd firmware\r\nmake\r\n\r\n# Install Python package\r\ncd ../rec_bms_manager\r\npip install -e .\r\n```\r\n\r\n## 📊 Performance Comparison\r\n\r\n| Metric | Original (LabVIEW) | Open REC 1Q |\r\n|--------|-------------------|-------------|\r\n| Flash Usage | 30KB (93%) | 13KB (40%) |\r\n| Main Loop | 30ms | 10ms |\r\n| Code Quality | Poor | Clean, documented |\r\n| Expandability | None | 19KB available |\r\n| Balancing Algorithm | Basic | Advanced |\r\n| Open Source | No | Yes |\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions! The Open REC 1Q Firmware project thrives on community involvement.\r\n\r\n### How to Contribute\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Commit your changes\r\n4. Push to your branch\r\n5. Create a Pull Request\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone with your fork\r\ngit clone https://github.com/yourusername/REC-BMSManagement.git\r\ncd REC-BMSManagement\r\n\r\n# Add upstream remote\r\ngit remote add upstream https://github.com/aaronsb/REC-BMSManagement.git\r\n\r\n# Install development dependencies\r\npip install -e rec_bms_manager[dev]\r\n\r\n# Run tests\r\npytest tests/\r\n```\r\n\r\n### Areas for Contribution\r\n- Hardware testing and validation\r\n- Additional protocol implementations\r\n- GUI development\r\n- Documentation improvements\r\n- Translation to other languages\r\n\r\n## 📄 License\r\n\r\nThe Open REC 1Q Firmware is released under the **MIT License** - see [LICENSE](LICENSE) file for details.\r\n\r\nThis open-source implementation allows you to:\r\n- Use commercially and personally\r\n- Modify and distribute\r\n- Create proprietary versions\r\n- Contribute improvements back to the community\r\n\r\n## ⚠️ Safety Disclaimer\r\n\r\n**IMPORTANT**: Battery management systems are safety-critical components. \r\n\r\n- This is third-party software not affiliated with or endorsed by REC BMS\r\n- Improper battery management can result in fire, explosion, or other hazards\r\n- Always follow safety guidelines and manufacturer recommendations\r\n- Test thoroughly before deploying in production\r\n- Use at your own risk\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- **REC BMS** for creating excellent battery management hardware\r\n- **Victron Energy** for the CAN protocol specification\r\n- **AVR Community** for toolchain and development support\r\n- **Contributors** who help improve this open-source project\r\n\r\n## 📞 Support \u0026 Community\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/aaronsb/REC-BMSManagement/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/aaronsb/REC-BMSManagement/discussions)\r\n- **Wiki**: [Project Wiki](https://github.com/aaronsb/REC-BMSManagement/wiki)\r\n\r\n## 🚦 Project Status\r\n\r\n### ✅ Completed\r\n- Python BMS manager implementation\r\n- RS485 protocol with 56000 baud support\r\n- Complete firmware reverse engineering\r\n- C++ firmware implementation based on actual hardware identification\r\n- MAX14752 multiplexer driver (GPIO-controlled, verified from board photos)\r\n- CAN bus Victron protocol\r\n- Cell balancing algorithms\r\n- Protection systems\r\n- Comprehensive documentation\r\n\r\n### 🚧 In Progress\r\n- Hardware testing with actual BMS units\r\n- Community feedback integration\r\n- Additional protocol support\r\n\r\n### ⚠️ Hardware Testing Required\r\n**CRITICAL**: This firmware is based on reverse engineering and board photo analysis.\r\nBefore production use, the following hardware validation is required:\r\n\r\n- **Physical Hardware Testing**: Load firmware onto actual REC 1Q BMS hardware\r\n- **Pin Assignment Verification**: Validate GPIO assignments through board trace analysis\r\n- **Component Function Testing**: Verify MAX14752 multiplexer control and ADC readings\r\n- **Communication Testing**: Confirm RS485 and CAN bus functionality\r\n- **Safety Testing**: Validate protection systems and cell balancing operation\r\n\r\n**Current Status**: Implementation is based on component identification and datasheet analysis.\r\nPin assignments are derived from firmware disassembly but require physical verification.\r\n\r\n### 📋 Roadmap\r\n- GUI application (Qt/Electron)\r\n- Mobile app support\r\n- Cloud monitoring integration\r\n- MQTT/Home Assistant integration\r\n- Multi-BMS support\r\n\r\n---\r\n\r\n**Open REC 1Q Firmware** - *Making battery management open, efficient, and community-driven.*\r\n\r\n*Not affiliated with REC BMS. \"REC\" and \"REC BMS\" are trademarks of their respective owners.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Frec-bmsmanagement","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Frec-bmsmanagement","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Frec-bmsmanagement/lists"}