https://github.com/aaronsb/rec-bmsmanagement
https://github.com/aaronsb/rec-bmsmanagement
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/aaronsb/rec-bmsmanagement
- Owner: aaronsb
- License: other
- Created: 2025-08-18T18:44:44.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-18T20:16:27.000Z (10 months ago)
- Last Synced: 2025-08-18T20:42:27.747Z (10 months ago)
- Language: Python
- Size: 4.43 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Open REC 1Q Firmware
An 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.
## ⛔ CRITICAL WARNING - READ BEFORE USE ⛔
**Installing Open REC 1Q Firmware will:**
- **VOID ALL WARRANTIES** from REC BMS permanently
- **ELIMINATE ALL SUPPORT** from REC BMS
- **POTENTIALLY BRICK YOUR DEVICE** requiring ISP programmer recovery
- **RISK BATTERY DAMAGE OR FIRE** if misconfigured
**This is THIRD-PARTY SOFTWARE not affiliated with REC BMS. Use at your own risk!**
See [LICENSE](LICENSE) for full disclaimers and warnings.
## 🎯 Project Overview
The **Open REC 1Q Firmware** project provides:
- **Python Library**: High-level BMS control and monitoring via RS485
- **C++ Firmware**: Clean, efficient replacement for LabVIEW-generated code
- **Complete Documentation**: Protocol specifications, hardware pinouts, algorithms
- **Development Tools**: Disassembly, analysis, and programming utilities
### Why Open REC 1Q Firmware?
The original REC BMS firmware was generated using LabVIEW, resulting in:
- 93% flash usage (30KB of 32KB)
- Inefficient code structure
- Limited expandability
- Poor maintainability
Our open-source C++ implementation provides:
- **40% flash usage** (13KB of 32KB)
- **Clean, maintainable code**
- **Room for additional features**
- **3x faster execution**
- **Community-driven development**
## 📚 Documentation
### Core Documentation
- [**Firmware Analysis Report**](docs/FIRMWARE_ANALYSIS.md) - Comprehensive analysis of the original firmware
- [**System Architecture**](docs/architecture.md) - Overall system design and data flow
- [**State Machine**](docs/state-machine.md) - BMS operational states and transitions
- [**Communication Protocols**](docs/protocols.md) - Complete RS485 and CAN message specifications
- [**MCU Pinout**](docs/pinout.md) - AT90CAN32 pin configuration and board layout
- [**Cell Management Algorithm**](docs/CELL_MANAGEMENT_ALGORITHM.md) - Battery management logic
### API Documentation
- [**Python API**](docs/python-api.md) - Python library usage and examples
- [**Firmware API**](docs/firmware-api.md) - C++ firmware functions and structures
### Development Guides
- [**Firmware Recreation Plan**](docs/FIRMWARE_RECREATION_PLAN.md) - Reverse engineering approach
- [**Project Plan**](docs/PROJECT_PLAN.md) - Development roadmap
- [**Baud Rate Guide**](docs/BAUD_RATE_GUIDE.md) - Custom baud rate configuration
### Reference Materials
- [PDF Documentation](docs/pdfs/) - REC BMS manuals and datasheets
- [Firmware Resources](resources/firmware/) - Original firmware and binaries
- [Disassembly Tools](resources/disassembly/) - Analysis scripts and tools
## 🚀 Quick Start
### Python Interface
```bash
# Install Python package
cd rec_bms_manager
pip install -e .
# Test connection
rec-bms auto-detect
# Monitor battery
rec-bms monitor -p /dev/ttyUSB0 -b 56000
```
```python
from rec_bms_manager import BMSManager
# Connect to BMS
bms = BMSManager(port='/dev/ttyUSB0', baud_rate=56000)
bms.connect()
# Get battery status
status = bms.get_status()
print(f"Voltage: {status['voltage']}V")
print(f"SOC: {status['soc']}%")
```
### Firmware Programming
```bash
# Build firmware
cd firmware
make clean && make
# Program via ISP (Con4 header)
./program_isp.sh
```
## 🏗️ Project Structure
```
REC-BMSManagement/
├── firmware/ # Open REC 1Q C++ firmware
│ ├── include/ # Header files
│ ├── src/ # Source files
│ ├── Makefile # Build configuration
│ └── program_isp.sh # ISP programming script
│
├── rec_bms_manager/ # Python management interface
│ ├── core/ # Core BMS communication
│ ├── utils/ # Utility functions
│ └── cli.py # Command-line interface
│
├── docs/ # Documentation
│ ├── architecture.md # System design
│ ├── protocols.md # Protocol specs
│ ├── pinout.md # Hardware pinouts
│ └── pdfs/ # Reference manuals
│
├── resources/ # Development resources
│ ├── firmware/ # Original firmware files
│ └── disassembly/ # Analysis tools
│
└── examples/ # Usage examples
```
## 🏆 Features
### Battery Management
- ✅ 16-cell lithium battery support (5-16 cells configurable)
- ✅ Individual cell voltage monitoring via dual MAX14752 analog multiplexers + 10-bit internal ADC
- ✅ Temperature monitoring via Dallas DS18B20 (up to 4 sensors)
- ✅ Current monitoring (shunt resistor, 18-bit ADC)
- ✅ Passive cell balancing (4.3Ω resistors, up to 900mA per cell)
- ✅ SOC/SOH calculation
- ✅ Multi-level protection (OV/UV/OC/OT/UT)
### Communication
- ✅ RS485 interface (38400/56000 baud)
- ✅ CAN bus (Victron Energy protocol)
- ✅ Bootloader support via RS485
- ✅ ISP programming via Con4 header
### Open Source Benefits
- ✅ Community-driven development
- ✅ Transparent implementation
- ✅ Customizable for specific needs
- ✅ No vendor lock-in
- ✅ Educational resource
## 🔧 Hardware Compatibility
### Supported Hardware
- **REC BMS 1Q** with AT90CAN32 microcontroller
- Compatible with all REC 1Q variants (4-16 cells)
- Works with existing REC BMS wiring and sensors
### Required Tools
- ISP programmer (USBasp, AVR ISP mkII, etc.)
- USB-to-RS485 adapter (FTDI recommended)
- Optional: CAN interface for monitoring
## 📦 Installation
### Prerequisites
```bash
# AVR Toolchain (choose your platform)
# Arch Linux
sudo pacman -S avr-gcc avr-libc avrdude
# Ubuntu/Debian
sudo apt-get install gcc-avr avr-libc avrdude
# macOS
brew tap osx-cross/avr
brew install avr-gcc avrdude
```
### Clone and Build
```bash
# Clone repository
git clone https://github.com/aaronsb/REC-BMSManagement.git
cd REC-BMSManagement
# Build firmware
cd firmware
make
# Install Python package
cd ../rec_bms_manager
pip install -e .
```
## 📊 Performance Comparison
| Metric | Original (LabVIEW) | Open REC 1Q |
|--------|-------------------|-------------|
| Flash Usage | 30KB (93%) | 13KB (40%) |
| Main Loop | 30ms | 10ms |
| Code Quality | Poor | Clean, documented |
| Expandability | None | 19KB available |
| Balancing Algorithm | Basic | Advanced |
| Open Source | No | Yes |
## 🤝 Contributing
We welcome contributions! The Open REC 1Q Firmware project thrives on community involvement.
### How to Contribute
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. Create a Pull Request
### Development Setup
```bash
# Clone with your fork
git clone https://github.com/yourusername/REC-BMSManagement.git
cd REC-BMSManagement
# Add upstream remote
git remote add upstream https://github.com/aaronsb/REC-BMSManagement.git
# Install development dependencies
pip install -e rec_bms_manager[dev]
# Run tests
pytest tests/
```
### Areas for Contribution
- Hardware testing and validation
- Additional protocol implementations
- GUI development
- Documentation improvements
- Translation to other languages
## 📄 License
The Open REC 1Q Firmware is released under the **MIT License** - see [LICENSE](LICENSE) file for details.
This open-source implementation allows you to:
- Use commercially and personally
- Modify and distribute
- Create proprietary versions
- Contribute improvements back to the community
## ⚠️ Safety Disclaimer
**IMPORTANT**: Battery management systems are safety-critical components.
- This is third-party software not affiliated with or endorsed by REC BMS
- Improper battery management can result in fire, explosion, or other hazards
- Always follow safety guidelines and manufacturer recommendations
- Test thoroughly before deploying in production
- Use at your own risk
## 🙏 Acknowledgments
- **REC BMS** for creating excellent battery management hardware
- **Victron Energy** for the CAN protocol specification
- **AVR Community** for toolchain and development support
- **Contributors** who help improve this open-source project
## 📞 Support & Community
- **Issues**: [GitHub Issues](https://github.com/aaronsb/REC-BMSManagement/issues)
- **Discussions**: [GitHub Discussions](https://github.com/aaronsb/REC-BMSManagement/discussions)
- **Wiki**: [Project Wiki](https://github.com/aaronsb/REC-BMSManagement/wiki)
## 🚦 Project Status
### ✅ Completed
- Python BMS manager implementation
- RS485 protocol with 56000 baud support
- Complete firmware reverse engineering
- C++ firmware implementation based on actual hardware identification
- MAX14752 multiplexer driver (GPIO-controlled, verified from board photos)
- CAN bus Victron protocol
- Cell balancing algorithms
- Protection systems
- Comprehensive documentation
### 🚧 In Progress
- Hardware testing with actual BMS units
- Community feedback integration
- Additional protocol support
### ⚠️ Hardware Testing Required
**CRITICAL**: This firmware is based on reverse engineering and board photo analysis.
Before production use, the following hardware validation is required:
- **Physical Hardware Testing**: Load firmware onto actual REC 1Q BMS hardware
- **Pin Assignment Verification**: Validate GPIO assignments through board trace analysis
- **Component Function Testing**: Verify MAX14752 multiplexer control and ADC readings
- **Communication Testing**: Confirm RS485 and CAN bus functionality
- **Safety Testing**: Validate protection systems and cell balancing operation
**Current Status**: Implementation is based on component identification and datasheet analysis.
Pin assignments are derived from firmware disassembly but require physical verification.
### 📋 Roadmap
- GUI application (Qt/Electron)
- Mobile app support
- Cloud monitoring integration
- MQTT/Home Assistant integration
- Multi-BMS support
---
**Open REC 1Q Firmware** - *Making battery management open, efficient, and community-driven.*
*Not affiliated with REC BMS. "REC" and "REC BMS" are trademarks of their respective owners.*