Nodel Recipe Development
Critical: Jython 2.5 Syntax
Node scripts execute under Jython 2.5.4. You MUST use Python 2.5-era syntax:
# CORRECT - Python 2.5 syntax
except Exception, e:
console.error('Error: %s' % e)
# WRONG - Python 3 syntax (will fail)
except Exception as e:
console.error(f'Error: {e}')See references/jython-syntax.md for complete syntax reference.
Recipe File Structure
A node recipe lives in a folder containing:
script.py- Main recipe logic (required)content/index.xml- Custom frontend definition (optional)content/css/custom.css- Custom styles (optional)content/js/custom.js- Custom JavaScript (optional)
Core Concepts
Parameters
Configure node behavior via the web interface:
param_ipAddress = Parameter({'title': 'IP Address', 'schema': {'type': 'string'}})
param_port = Parameter({'title': 'Port', 'schema': {'type': 'integer'}, 'default': 9999})Local Actions
Commands this node exposes (can be triggered by bindings or REST API):
@local_action({'schema': {'type': 'string', 'enum': ['On', 'Off']}})
def power(arg):
'''{"group": "Power", "order": 1}'''
tcp.send('POWER %s\r\n' % arg)Alternative pattern:
- Naming convention also works:
def local_action_PowerOn(arg=None):...
Local Events
State this node emits (can be bound by other nodes):
local_event_Status = LocalEvent({'schema': {'type': 'object'}})
# Emit when state changes
local_event_Status.emit({'power': 'On', 'volume': 50})Remote Bindings
Connect to other nodes:
# Call actions on other nodes
remote_action_DisplayPower = RemoteAction()
remote_action_DisplayPower.call('On')
# Receive events from other nodes
def remote_event_DisplayStatus(arg):
console.info('Display status: %s' % arg)Lifecycle Functions
def main():
'''Called when node starts. Set up initial state.'''
console.info('Node starting...')
@after_main
def setup():
'''Called after main() and parameter loading. Configure connections.'''
tcp.setDest('%s:%s' % (param_ipAddress, param_port))
@at_cleanup
def cleanup():
'''Called when node shuts down. Clean up resources.'''
tcp.close()Network Protocols
TCP, UDP, and HTTP are available via the toolkit. See references/toolkit-api.md for complete documentation with examples.
Timers
# Repeating timer (poll every 30 seconds)
Timer(poll_status, 30)
# One-time delayed call
call(setup_connection, 5)
# Stoppable timer
status_timer = Timer(check_status, 60, stopped=True)
status_timer.start()
status_timer.stop()Console Logging
console.log("Light gray - verbose/debug")
console.info("Blue - informational")
console.warn("Orange - warning")
console.error("Red - error")Common Patterns
Device Control with Polling
def poll_status():
tcp.send('STATUS?\r\n')
Timer(poll_status, 30)
def tcp_received(data):
if 'POWER=' in data:
local_event_Status.emit({'power': data.split('=')[1]})Status Monitoring
local_event_Status = LocalEvent({'schema': {'type': 'object', 'properties': {
'level': {'type': 'integer'},
'message': {'type': 'string'}
}}})
_lastReceive = 0
def statusCheck():
diff = (system_clock() - _lastReceive) / 1000.0
if diff > 90:
local_event_Status.emit({'level': 2, 'message': 'No response'})
else:
local_event_Status.emit({'level': 0, 'message': 'OK'})
Timer(statusCheck, 60)Dynamic Action Creation
def build_presets():
for preset in PRESET_NAMES:
create_local_action('Preset %s' % preset,
lambda arg, p=preset: activate_preset(p),
{'group': 'Presets', 'schema': {'type': 'null'}})Error Handling
@local_action({})
def riskyOperation(arg):
try:
result = perform_operation(arg)
local_event_Success.emit(result)
except Exception, e:
console.error('Operation failed: %s' % e)
local_event_Error.emit(str(e))Development Philosophy
- Simplicity First - Keep code minimal and readable
- Maintainability > Cleverness - Prefer explicit over implicit
- DRY - Extract common patterns to helper functions
- Defensive Coding - Handle network failures gracefully