Restructured and updated documentation

Splitting up the documentation in an end user and developer part.
victronenergy · Nov 5, 2024 · 13ece4e · 13ece4e
1 parent 7ce0ab1
commit 13ece4e
Show file tree

Hide file tree

Showing 40 changed files with 552 additions and 346 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
@@ -0,0 +1,228 @@
+# Development Guide
+
+## Architecture Overview
+
+### Core Components
+
+1. **Victron Config Node**
+   - Manages D-Bus connection
+   - Initializes core services
+   - Maintains system configuration
+
+2. **VictronClient**
+   - Handles D-Bus communication
+   - Manages message subscriptions
+   - Maintains service cache
+
+3. **SystemConfiguration**
+   - Tracks available services
+   - Provides service metadata
+   - Manages device discovery
+
+```mermaid
+graph TD
+    A[Victron Config Node] --> B[VictronClient]
+    A --> C[SystemConfiguration]
+    B --> D[D-Bus]
+    C --> E[Service Cache]
+```
+
+## Development Environment Setup
+
+### Prerequisites
+1. Node.js (LTS version recommended)
+2. Access to a GX device or simulator
+3. Git
+4. Basic understanding of:
+   - Node-RED node development
+   - D-Bus
+   - Victron Energy systems
+
+### Initial Setup
+
+1. **Clone Repository**
+   ```bash
+   git clone https://github.com/victronenergy/node-red-contrib-victron.git
+   cd node-red-contrib-victron
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Link for Development**
+   ```bash
+   npm link
+   cd ~/.node-red
+   npm link @victronenergy/node-red-contrib-victron
+   ```
+
+## Adding New Nodes
+
+### 1. Define Service Whitelist
+```javascript
+// scripts/service-whitelist.js
+module.exports = {
+    "input-new-node": {
+        "service_type": [
+            "/Path/To/Service",
+        ]
+    }
+}
+```
+
+### 2. Generate Service Definitions
+```bash
+node parse-services.js ./missingpaths.json
+```
+
+### 3. Create Node Files
+```javascript
+// src/nodes/victron-nodes.js
+RED.nodes.registerType('victron-input-new-node', BaseInputNode);
+
+// src/nodes/victron-nodes.html
+registerInputNode('victron-input-new-node', 'New Node', 'input-new-node');
+```
+
+### 4. Update System Configuration
+```javascript
+// src/services/victron-system.js
+listAvailableServices() {
+    return {
+        "input-new-node": this.getNodeServices("input-new-node"),
+        // ...
+    }
+}
+```
+
+## Testing
+
+### Manual Testing
+1. Deploy to test environment
+2. Verify node behavior
+3. Test error conditions
+4. Validate documentation
+
+## Release Process
+
+### 1. Update Dependencies
+```bash
+rm ./package-lock.json ./npm-shrinkwrap.json ./yarn.lock
+rm -rf ./node_modules
+npm install --omit=dev
+```
+
+### 2. Version Bump
+```bash
+npm version [major|minor|patch]
+```
+
+### 3. Build and Test
+```bash
+npm run build
+npm test
+```
+
+### 4. Release
+```bash
+npm run release
+npm publish
+```
+
+## Documentation
+
+### Generating Documentation
+```bash
+# Update node documentation
+node scripts/service2doc.js -s src/services/services.json -r src/nodes/victron-nodes.html -t nodered
+
+# Update wiki
+node scripts/service2doc.js -s src/services/services.json -r src/nodes/victron-nodes.html -t md
+```
+
+### Documentation Standards
+1. Keep `README.md` current
+2. Update `USER_GUIDE.md` for user-facing changes
+3. Update examples for new features
+
+## Contributing Guidelines
+
+### Pull Request Process
+1. Fork repository
+2. Create feature branch
+3. Make changes
+4. Update documentation
+5. Submit PR
+
+### Code Style
+- Follow ESLint configuration
+- Use meaningful variable names
+- Comment complex logic
+- Keep functions focused
+
+### Commit Messages
+- Use conventional commits
+- Reference issues
+- Describe changes clearly
+
+## Debug Tools
+
+Debugging can be done moste easily using VSCode, opening the
+`node-red-contrib-victron.code-workspace` file. There is also a `launch.json`
+file, which connects to `venus.local`, using the tcp connection to connect to
+the GX devices' `dbus`. See the section on `InsecureDbusOverTcp` in the 
+[INSTALL.md](INSTALL.md#installation-steps)) file for more information on setting that up.
+
+### Environment Variables
+```bash
+# Debug all components
+export DEBUG=node-red-contrib-victron*
+
+# Debug specific component
+export DEBUG=node-red-contrib-victron:dbus
+```
+
+### D-Bus Monitoring
+```bash
+dbus-monitor "type='signal',sender='com.victronenergy.battery.ttyO1'"
+```
+
+### Log Analysis
+1. Enable debug logging
+2. Check Node-RED logs
+3. Monitor D-Bus messages
+4. Review system logs
+
+## Advanced Topics
+
+### Custom Service Types
+1. Define service specification
+2. Update parser
+3. Add to whitelist
+4. Create node implementation
+
+### Virtual Device Creation
+1. Define device type
+2. Implement D-Bus interface
+3. Create node wrapper
+4. Add documentation
+
+### Performance Optimization
+1. Minimize D-Bus traffic
+2. Use efficient data structures
+3. Implement caching
+4. Profile memory usage
+
+## Support and Resources
+
+### Developer Resources
+- [Node-RED Documentation](https://nodered.org/docs/creating-nodes/)
+- [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html)
+- [Victron Modbus-TCP Register List](https://www.victronenergy.com/support-and-downloads/technical-information)
+
+### Community
+- [Victron Community Forum](https://community.victronenergy.com)
+- [GitHub Issues](https://github.com/victronenergy/node-red-contrib-victron/issues)
+- [Developer Mailing List](mailto:dev@victronenergy.com)
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -0,0 +1,148 @@
+# Installation Guide
+
+## Option 1: Venus OS Large (Recommended)
+
+The easiest way to use Victron Energy nodes is through Venus OS Large, where both Node-RED and these nodes come pre-installed.
+
+1. Install Venus OS Large on your GX device
+   - Download from [Victron Professional](https://professional.victronenergy.com/)
+   - Follow the [installation instructions](https://www.victronenergy.com/live/venus-os:large)
+
+2. Access Node-RED
+   - Open your web browser
+   - Navigate to `http://<venus-ip>:1880`
+   - The Victron nodes will be available in the palette
+
+## Option 2: Manual Installation
+
+### Prerequisites
+- Node-RED installed
+- A Victron system with a GX device
+- Network access to the GX device
+
+### Warning
+⚠️ Manual installation requires modifying D-Bus settings. Incorrect configuration can render your GX device unusable. Only proceed if you:
+- Are comfortable with system configuration
+- Have a backup plan
+- Are on a trusted network
+- Understand the security implications
+
+### Installation Steps
+
+1. **Install Node-RED** (if not already installed)
+   ```bash
+   npm install -g node-red
+   ```
+
+2. **Install Victron nodes**
+   ```bash
+   cd ~/.node-red
+   npm install @victronenergy/node-red-contrib-victron
+   ```
+
+3. **Configure D-Bus Access**
+
+   Option A: Direct Socket Connection (Recommended)
+   - Uses system socket by default
+   - No additional configuration needed
+   - Socket path: `/var/run/dbus/system_bus_socket`
+
+   Option B: TCP Connection
+   ```bash
+   # On the GX device
+   dbus -y com.victronenergy.settings /Settings/Services/InsecureDbusOverTcp SetValue 1
+   # Reboot required
+   ```
+
+4. **Set Environment Variables** (if needed)
+   ```bash
+   # For TCP connection
+   export NODE_RED_DBUS_ADDRESS=venus.local:78
+
+   # For debugging
+   export DEBUG=node-red-contrib-victron*
+   ```
+
+5. **Start Node-RED**
+   ```bash
+   node-red
+   ```
+
+### Verification
+
+1. Open Node-RED interface
+   ```
+   http://localhost:1880
+   ```
+
+2. Check for Victron nodes in the palette
+   - Look for the Victron Energy section
+   - Verify available nodes match your system
+
+3. Test connection
+   - Drop an input node onto the canvas
+   - Configure device and measurement
+   - Deploy and check for data
+
+### Troubleshooting
+
+1. **Connection Issues**
+   - Verify GX device is accessible
+   - Check D-Bus configuration
+   - Review environment variables
+
+2. **Missing Nodes**
+   - Check npm installation
+   - Verify Node-RED version compatibility
+   - Review Node-RED logs
+
+3. **Data Not Flowing**
+   - Confirm device is available on D-Bus
+   - Check node configuration
+   - Enable debug messages
+
+### Security Considerations
+
+1. **Network Security**
+   - Use on trusted networks only
+   - Consider VPN for remote access
+   - Monitor for unauthorized access
+
+2. **Access Control**
+   - Enable Node-RED authentication
+   - Use strong passwords
+   - Limit network exposure
+
+3. **Updates**
+   - Keep Node-RED updated
+   - Monitor for security advisories
+   - Update nodes regularly
+
+### Additional Configuration
+
+#### Custom Socket Path
+```bash
+export DBUS_SYSTEM_BUS_ADDRESS="unix:path=/custom/path/to/socket"
+```
+
+#### Session Bus
+```bash
+export DBUS_SESSION_BUS_ADDRESS="unix:path=/custom/path/to/session/socket"
+```
+
+#### Debug Options
+```bash
+# Full debug output
+export DEBUG=node-red-contrib-victron*
+
+# Specific component debugging
+export DEBUG=node-red-contrib-victron:dbus
+```
+
+## Support
+
+For installation help:
+1. Check [Troubleshooting](#troubleshooting) section
+2. Visit [Victron Community](https://community.victronenergy.com)
+3. Review [GitHub Issues](https://github.com/victronenergy/node-red-contrib-victron/issues)
+4. Contact your Victron dealer for Venus OS support