fix(spine): guard nil remoteFeature in SubscribeToRemote/BindToRemote

.github/workflows/default.yml

@@ -32,8 +32,7 @@ jobs:
         uses: golangci/golangci-lint-action@master
         with:
           version: latest
-          skip-pkg-cache: true
-          skip-build-cache: true
+          skip-cache: true
           args: --timeout=3m --issues-exit-code=0 ./...
 
       - name: Test

ARCHITECTURE.md

@@ -0,0 +1,232 @@
+# SPINE-Go Architecture Documentation
+
+This document explains the overall architecture of the SPINE-Go library, which provides an implementation of the EEBUS SPINE 1.3 specification in Go.
+
+## Overview
+
+SPINE-Go is a library that implements the SPINE (Smart Premises Interoperable Neutral-message Exchange) protocol, which is part of the EEBUS specification for smart energy management systems. The library provides a complete stack for creating and managing SPINE devices that can communicate with each other over networks.
+
+## Core Components
+
+The architecture is organized into several key packages, each serving a specific purpose:
+
+### 1. API Package (`api/`)
+
+Contains the core interfaces that define contracts for all major components. This package serves as the foundation for the entire architecture and enables dependency injection and testing through mocking.
+
+**Key Interfaces:**
+- `DeviceInterface` - Common device functionality
+- `DeviceLocalInterface` - Local device management
+- `DeviceRemoteInterface` - Remote device representation  
+- `EntityInterface` - Entity management
+- `FeatureInterface` - Feature functionality
+- `SenderInterface` - Message sending capabilities
+- `EventHandlerInterface` - Event handling
+
+### 2. Model Package (`model/`)
+
+Contains the Go representation of the SPINE data model with proper JSON serialization support and EEBUS tags for generic feature-to-function mapping.
+
+**Key Components:**
+- Data structures for all SPINE message types
+- Command and function definitions
+- Network management types
+- Address and identification structures
+
+### 3. SPINE Package (`spine/`)
+
+The main implementation package containing the core business logic for SPINE devices, entities, features, functions, and data management.
+
+## Hierarchical Architecture
+
+The SPINE architecture follows a hierarchical structure:
+
+```
+Device
+├── Entity (0..n)
+    ├── Feature (0..n)
+        ├── Function (0..n)
+            └── Data
+```
+
+### Device Level
+
+**DeviceLocal** (`device_local.go`)
+- Represents the local SPINE device
+- Manages local entities and remote device connections
+- Handles incoming SPINE messages and routing
+- Provides node management, subscription management, and binding management
+- Contains device information like brand, model, serial number
+
+**DeviceRemote** (`device_remote.go`)
+- Represents a remote SPINE device
+- Manages remote entities discovered through detailed discovery
+- Handles incoming messages from the associated device
+- Maintains connection to the local device
+
+### Entity Level
+
+**EntityLocal** (`entity_local.go`)
+- Represents a local entity within the device
+- Manages local features
+- Handles heartbeat management for non-device-information entities
+- Examples: EV charging point, heat pump, battery storage
+
+**EntityRemote** (`entity_remote.go`)
+- Represents a remote entity from a connected device
+- Manages remote features discovered through detailed discovery
+- Maintains reference to parent remote device
+
+### Feature Level
+
+**FeatureLocal** (`feature_local.go`)
+- Implements specific SPINE feature functionality
+- Manages function data and operations
+- Handles subscriptions and bindings to remote features
+- Processes incoming messages for the feature
+- Examples: Device Diagnosis, Load Control, Measurement
+
+**FeatureRemote** (`feature_remote.go`)
+- Represents a remote feature
+- Stores data received from remote devices
+- Maintains operation capabilities and response delays
+
+## Communication Architecture
+
+### Message Flow
+
+1. **Outgoing Messages:**
+   ```
+   Local Feature → Sender → SHIP Connection → Network
+   ```
+
+2. **Incoming Messages:**
+   ```
+   Network → SHIP Connection → Device.ProcessCmd() → Feature.HandleMessage()
+   ```
+
+### Key Communication Components
+
+**Sender** (`send.go`)
+- Handles all outgoing SPINE messages
+- Manages message counters and caching
+- Supports different message types: Request, Reply, Notify, Write
+- Implements message deduplication for certain message types
+
+**Message Processing**
+- `DeviceLocal.ProcessCmd()` - Main entry point for incoming messages
+- Routes messages to appropriate local features
+- Handles acknowledgments and error responses
+- Manages message validation and addressing
+
+## Management Systems
+
+### Node Management (`nodemanagement.go`)
+
+The Node Management feature is present on every device (Entity 0, Feature 0) and handles:
+
+- **Detailed Discovery**: Exchange of device, entity, and feature information
+- **Destination Lists**: Available communication endpoints
+- **Use Case Data**: Supported use cases and their configurations
+- **Subscription Management**: Managing data subscriptions between features
+- **Binding Management**: Managing persistent connections between features
+
+### Subscription Manager (`subscription_manager.go`)
+
+Manages subscriptions between client and server features:
+- Tracks active subscriptions between local and remote features
+- Handles subscription requests and deletions
+- Automatically notifies subscribed features when data changes
+- Manages subscription data persistence
+
+### Binding Manager (`binding_manager.go`)
+
+Manages bindings (persistent connections) between features:
+- Tracks active bindings between client and server features
+- Handles binding requests and deletions
+- Enforces binding constraints (e.g., one remote binding per local server feature)
+- Manages binding data persistence
+
+### Heartbeat Manager (`heartbeat_manager.go`)
+
+Manages heartbeat functionality for device diagnosis:
+- Sends periodic heartbeat messages to subscribed remote features
+- Configurable heartbeat intervals
+- Automatically starts/stops based on subscription state
+- Used for connection monitoring and fault detection
+
+## Event System (`events.go`)
+
+The library includes a comprehensive event system for notifying applications about important state changes:
+
+**Event Types:**
+- `EventTypeDeviceChange` - Device connection/disconnection
+- `EventTypeEntityChange` - Entity addition/removal
+- `EventTypeSubscriptionChange` - Subscription state changes
+- `EventTypeBindingChange` - Binding state changes  
+- `EventTypeDataChange` - Feature data updates
+
+**Event Handling Levels:**
+- `EventHandlerLevelCore` - For internal library components (synchronous)
+- `EventHandlerLevelApplication` - For application code (asynchronous)
+
+## Data Flow Examples
+
+### Device Discovery Process
+
+1. Local device connects to remote device via SHIP
+2. Local device requests detailed discovery from remote device
+3. Remote device responds with device, entity, and feature information
+4. Local device creates corresponding remote device, entity, and feature objects
+5. Events are published for each discovered component
+6. Applications can then establish subscriptions and bindings
+
+### Data Subscription Process
+
+1. Local client feature requests subscription to remote server feature
+2. Subscription manager validates and stores the subscription
+3. Remote device acknowledges the subscription
+4. When remote feature data changes, notifications are sent to subscriber
+5. Local feature updates its cached data and publishes events
+
+### Feature Communication
+
+1. Local feature wants to read data from remote feature
+2. Sender creates and sends a read request message
+3. Remote feature receives request and sends reply with data
+4. Local feature processes reply, updates cache, and publishes events
+5. Applications receive events and can access the updated data
+
+## Integration Points
+
+### SHIP Integration
+
+SPINE-Go integrates with the SHIP (Smart Home IP) protocol layer:
+- Uses SHIP for device discovery and connection establishment
+- SHIP handles network-level communication and security
+- SPINE messages are transported as SHIP payload
+
+### Application Integration
+
+Applications integrate with SPINE-Go through:
+- Event subscriptions for state change notifications
+- Direct API calls for data access and control
+- Feature-specific helper libraries for use case implementations
+
+## Thread Safety
+
+The library is designed to be thread-safe:
+- Uses mutexes to protect shared data structures
+- Event publishing is handled safely across goroutines
+- Message processing includes proper synchronization
+- Managers use appropriate locking for concurrent access
+
+## Testing Architecture
+
+The architecture supports comprehensive testing through:
+- **Mocks Package** (`mocks/`) - Auto-generated mocks for all interfaces
+- **Integration Tests** (`integration_tests/`) - End-to-end testing scenarios
+- **Unit Tests** - Extensive unit test coverage for individual components
+- **Test Helpers** - Common testing utilities and data generators
+
+This modular and interface-driven architecture provides flexibility, testability, and clear separation of concerns while maintaining compliance with the EEBUS SPINE specification.

CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at <mail@andreaslinde.de>. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/), version
+[1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) and
+[2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md),
+and was generated by [contributing-gen](https://github.com/bttger/contributing-gen).