Welcome! This guide will help you get started contributing to CGateWeb, a Node.js bridge that connects Clipsal C-Bus automation systems to MQTT for Home Assistant integration.
- Node.js 20.19+ (or 22.13+, or 24+): matches the
enginesfield inpackage.json - C-Gate Server: Clipsal's C-Bus automation gateway software
- MQTT Broker: Like Mosquitto or built into Home Assistant
- Git: For version control and contributing
-
Clone the repository
git clone <repository-url> cd cgateweb
-
Install dependencies
npm install
-
Copy and configure settings
cp settings.js.example settings.js # Edit settings.js with your C-Gate and MQTT broker detailssettings.jsis git-ignored — the copy above creates it, and your local edits should never be committed. Every setting, its default and its Home Assistant add-on equivalent are in docs/SETTINGS.md; the defaults themselves live insrc/defaultSettings.js. Credentials can be kept out of the file entirely via theCGATE_*/MQTT_*environment variables (see the README). -
Run tests
npm test -
Run the application
npm start
CGateWeb acts as a bidirectional bridge:
C-Bus Devices ←→ C-Gate Server ←→ CGateWeb ←→ MQTT Broker ←→ Home Assistant
CgateWebBridge(src/cgateWebBridge.js): Main orchestration classCBusEvent(src/cbusEvent.js): Parses events from C-GateCBusCommand(src/cbusCommand.js): Parses MQTT commands for C-GateMqttManager(src/mqttManager.js): Handles MQTT connectionsCgateConnection(src/cgateConnection.js): Manages C-Gate socket connectionsHaDiscovery(src/haDiscovery.js): Home Assistant device discoveryThrottledQueue(src/throttledQueue.js): Rate-limited message processing
Understanding C-Bus addressing is essential:
- Network: Typically 254 (default network)
- Application: Device type (56 = lighting, 36 = triggers, etc.)
- Group: Individual device/channel number
- Level: 0-255 brightness for lights (0 = off, 255 = full brightness)
Example: 254/56/4 = Network 254, Lighting Application, Group 4
Incoming Commands (MQTT → C-Gate):
- MQTT:
cbus/write/254/56/4/switchpayloadON - C-Gate:
on //PROJECT/254/56/4
Outgoing Events (C-Gate → MQTT):
- C-Gate:
lighting on 254/56/4 - MQTT:
cbus/read/254/56/4/statepayloadON
- Use descriptive variable names that explain C-Bus concepts
- Follow existing patterns in the codebase
- Add JSDoc comments for public methods and complex logic
- Use ES6+ features (const/let, arrow functions, destructuring)
- Keep functions focused and small
Before submitting any changes:
- Write tests first for new functionality
- Run all tests:
npm test - Ensure 100% test pass rate — the whole suite must be green, not just the file you touched
- Update tests when modifying existing functionality
Tests use Jest with extensive mocking:
// Example test pattern
describe('ClassName', () => {
let mockDependency;
beforeEach(() => {
mockDependency = {
method: jest.fn()
};
});
it('should handle specific scenario', () => {
// Arrange
const instance = new ClassName(mockDependency);
// Act
const result = instance.method();
// Assert
expect(result).toBe(expectedValue);
expect(mockDependency.method).toHaveBeenCalledWith(expectedArgs);
});
});- Add command constant to
src/constants.js - Update
CBusCommand._parsePayload()method - Add handler method in
CgateWebBridge - Write tests for the new command type
- Add response code constant to
src/constants.js - Update
CgateWebBridge._processCommandResponse()switch statement - Implement response handler method
- Write tests for the new response type
Turn up the log level in settings.js:
exports.log_level = 'debug'; // 'error' | 'warn' | 'info' | 'debug' | 'trace'log_level is the real control. The older logging: true flag is effectively dead: consumers read settings.log_level || (settings.logging ? 'info' : 'warn'), and defaultSettings always supplies a log_level, so the logging branch is never reached.
LOG_LEVEL=debug npm start works too, but only for components that build their logger without a level (most modules). The bridge, event publisher and connection manager take theirs from settings.log_level, so set that in settings.js when you want the whole bridge verbose.
Log level is hot-reloadable: kill -USR1 <pid> (or systemctl reload cgateweb) re-reads settings.js and applies the new level without a restart.
- Create feature branch:
git checkout -b feature/your-feature-name - Make changes with tests
- Verify tests pass:
npm test - Commit with clear messages: Focus on the "why" not just "what"
- Push and create PR
Use clear, descriptive commit messages:
Add support for C-Bus trigger commands
- Implement MQTT command parsing for trigger devices
- Add trigger command handlers in bridge
- Include comprehensive tests for trigger functionality
Resolves #123
- All tests pass
- New functionality has tests
- JSDoc comments added for public methods
- No breaking changes to existing API
- Error handling for edge cases
- Logging for debugging
- Settings validation if applicable
- C-Gate Manual: Essential reading for C-Bus concepts
- C-Bus Toolkit: GUI tool for testing C-Gate connections
- Existing tests: Great examples of expected behavior
"Connection refused to C-Gate"
- Verify C-Gate is running and accessible
- Check firewall settings
- Confirm port numbers: 20023 for commands (
cbuscommandport) and 20025 for the status-change stream cgateweb listens on (cbuseventport). C-Gate also has an event port on 20024, but cgateweb does not use it.
"MQTT publish failed"
- Verify MQTT broker is running
- Check authentication credentials
- Test with MQTT client tools
"Tests failing after changes"
- Run
npm testto see specific failures - Check if you broke existing functionality
- Update test expectations if behavior intentionally changed
cgateweb/
├── src/ # Main source code
│ ├── cgateWebBridge.js # Main bridge class
│ ├── cbusEvent.js # C-Bus event parsing
│ ├── cbusCommand.js # MQTT command parsing
│ ├── constants.js # Shared constants
│ └── ...
├── tests/ # Jest test files
├── settings.js.example # Configuration template
├── index.js # Application entry point
└── package.json # Dependencies and scripts
This project aims to be:
- Reliable: Robust error handling and comprehensive testing
- Maintainable: Clear code structure and documentation
- Accessible: Easy for newcomers to understand and contribute
- Stable: Changes shouldn't break existing integrations
Thank you for contributing to CGateWeb! Your help makes C-Bus automation more accessible to the open source community.