Nexus-1 SDK Manual - Developer Guide

Quick Start

Get started building modules for the Nexus-1 platform in minutes.

1. Install the SDK

# Install via NuGet Package Manager
dotnet add package Nexus.SDK.Client

# Or via Package Manager Console
Install-Package Nexus.SDK.Client

# Or add to .csproj file
<PackageReference Include="Nexus.SDK.Client" Version="1.0.0" />

This will automatically install the minimal required dependencies (Microsoft.Extensions abstractions).

# Install via pip
pip install nexus-sdk-client

# Or install from requirements.txt
echo "nexus-sdk-client>=1.0.0" >> requirements.txt
pip install -r requirements.txt

# For development installation
pip install -e nexus-sdk-client[dev]

The Python SDK provides async/await support and type hints for better development experience.

# Using CMake
# Add to CMakeLists.txt:
find_package(NexusSDKClient REQUIRED)
target_link_libraries(your_module PRIVATE NexusSDKClient::Core)

# Using vcpkg
vcpkg install nexus-sdk-client

# Using Conan
conan install nexus-sdk-client/1.0.0@

The C++ SDK provides header-only interfaces with modern C++17 support.

% Option 1: Add to MATLAB path
addpath('/path/to/nexus-sdk-client-matlab')
savepath  % Save for future sessions

% Option 2: Install from MATLAB File Exchange
% Search for "NEXUS-1 SDK Client" in File Exchange

% Option 3: Install from Add-On Explorer
% Home tab > Add-Ons > Get Add-Ons
% Search for "NEXUS-1 SDK Client for MATLAB"

MATLAB SDK provides object-oriented interfaces compatible with MATLAB R2019b and later.

% Option 1: VI Package Manager (VIPM)
% 1. Open VI Package Manager
% 2. Search for "NEXUS-1 SDK Client"
% 3. Click Install

% Option 2: Manual Installation
% 1. Download from ni.com/tools/nexus-sdk-client
% 2. Extract to LabVIEW/user.lib/
% 3. Restart LabVIEW

% Option 3: LabVIEW Tools Network
% Tools > VI Package Manager > Browse

LabVIEW SDK provides VIs and type definitions for LabVIEW 2019 and later.

2. Create Your Module

Module Capabilities

Nexus uses a capability-based security model where modules must declare their required capabilities in the manifest file. This ensures modules only access resources and APIs they need.

How Capabilities Work

When the Nexus host loads your module, it:

Reads the capabilities declared in the manifest file
Validates that required capabilities are available in the system
Grants only the declared capabilities to the module
Enforces capability checks at runtime for sensitive operations
Provides the granted capabilities via the module context

Common System Capabilities

READ_SENSORS - Read sensor data
WRITE_CONTROLS - Write to control systems
PUBLISH_TELEMETRY - Publish telemetry data
STORAGE_READ - Read from persistent storage
STORAGE_WRITE - Write to persistent storage
NETWORK_ACCESS - Make network requests
HARDWARE_ACCESS - Access hardware devices
SYSTEM_CONFIG - Read system configuration

using Nexus.Contracts;
using Nexus.SDK.Client;
using Microsoft.Extensions.Logging;

// Simple module that inherits from ModuleBase
public class TemperatureMonitor : ModuleBase
{
    private Timer? _timer;
    private double _threshold = 75.0;

    // Called by host during initialization
    protected override async Task OnInitializeAsync()
    {
        // Logger is automatically available from ModuleBase
        Logger.LogInformation("Temperature monitor initializing");
        
        // Access configuration from manifest
        _threshold = Configuration.GetValue("threshold", 75.0);
        
        // Module capabilities are defined in the manifest file
        // The host ensures we only have access to declared capabilities
        Logger.LogInformation("Temperature threshold set to {Threshold}°C", _threshold);
            
        await Task.CompletedTask;
    }

    // Called by host when module should start
    public override async Task StartAsync(CancellationToken cancellationToken)
    {
        await base.StartAsync(cancellationToken);
        
        // Subscribe to temperature threshold commands
        await MessageBus.Subscribe(HandleThresholdCommand);
        
        // Start monitoring
        _timer = new Timer(CheckTemperature, null, TimeSpan.Zero, TimeSpan.FromSeconds(5));
    }

    private async Task HandleThresholdCommand(SetThresholdCommand command)
    {
        Logger.LogInformation("Threshold set to {Threshold}", command.Threshold);
        // Update threshold...
    }

    private async void CheckTemperature(object? state)
    {
        // Read temperature (simulated)
        var temp = ReadTemperature();
        
        // Check against threshold
        if (temp > _threshold)
        {
            Logger.LogWarning("Temperature {Temp}°C exceeds threshold {Threshold}°C", temp, _threshold);
        }
        
        // Publish telemetry
        // The host ensures we can only publish if we have the PUBLISH_TELEMETRY capability
        await MessageBus.PublishAsync("telemetry/temperature", new TemperatureReading
        {
            Value = temp,
            Timestamp = DateTime.UtcNow
        });
    }

    public override async Task StopAsync(CancellationToken cancellationToken)
    {
        _timer?.Dispose();
        await base.StopAsync(cancellationToken);
    }
}

// Message contracts using SDK base classes
public class SetThresholdCommand : RequestMessage
{
    public double Threshold { get; set; }
}

public class TemperatureReading : EventMessage
{
    public double Value { get; set; }
}

from nexus_sdk import Module, RequestMessage, EventMessage, module
import asyncio
from datetime import datetime

class TemperatureMonitor(Module):
    def __init__(self):
        super().__init__()
        self._timer_task = None
        self._threshold = 75.0
        
    async def on_initialize(self):
        """Called by host during initialization"""
        self.logger.info("Temperature monitor initializing")
        
        # Access configuration from manifest
        self._threshold = self.config.get("threshold", 75.0)
        
        # Module capabilities are defined in the manifest file
        # The host ensures we only have access to declared capabilities
        self.logger.info(f"Temperature threshold set to {self._threshold}°C")
        
    async def start(self):
        """Called by host when module should start"""
        # Subscribe to temperature threshold commands
        await self.message_bus.subscribe(
            SetThresholdCommand, 
            self.handle_threshold_command
        )
        
        # Start monitoring
        self._timer_task = asyncio.create_task(self.monitor_temperature())
        
    async def handle_threshold_command(self, command: SetThresholdCommand):
        self.logger.info(f"Threshold set to {command.threshold}")
        # Update threshold...
        
    async def monitor_temperature(self):
        while True:
            # Read temperature (simulated)
            temp = self.read_temperature()
            
            # Publish reading
            await self.message_bus.publish(
                "telemetry/temperature",
                TemperatureReading(value=temp)
            )
            
            await asyncio.sleep(5)
            
    async def stop(self):
        """Called by host when module should stop"""
        if self._timer_task:
            self._timer_task.cancel()

# Message contracts using SDK base classes
class SetThresholdCommand(RequestMessage):
    threshold: float
    
class TemperatureReading(EventMessage):
    value: float

#include 
#include 
#include 

using namespace nexus::sdk;

// Message contracts using SDK base classes
struct SetThresholdCommand : public RequestMessage {
    double threshold;
};

struct TemperatureReading : public EventMessage {
    double value;
};

class TemperatureMonitor : public ModuleBase {
public:
    TemperatureMonitor() : ModuleBase("temperature-monitor", "1.0.0") {}

protected:
    // Called by host during initialization
    async::task OnInitializeAsync() override {
        logger()->info("Temperature monitor initializing");
        
        // Access capabilities granted in manifest
        auto capabilities = module_info().capabilities;
        logger()->info("Granted capabilities: {}", fmt::join(capabilities, ", "));
        
        co_return;
    }

    // Called by host when module should start
    async::task StartAsync(CancellationToken token) override {
        co_await ModuleBase::StartAsync(token);
        
        // Subscribe to temperature threshold commands
        co_await message_bus()->Subscribe(
            [this](const SetThresholdCommand& cmd) -> async::task {
                co_await HandleThresholdCommand(cmd);
            });
        
        // Start monitoring
        monitor_task_ = MonitorTemperature(token);
    }

private:
    async::task HandleThresholdCommand(const SetThresholdCommand& command) {
        logger()->info("Threshold set to {}", command.threshold);
        threshold_ = command.threshold;
        co_return;
    }

    async::task MonitorTemperature(CancellationToken token) {
        while (!token.is_cancellation_requested()) {
            // Read temperature (simulated)
            auto temp = ReadTemperature();
            
            // Publish reading
            co_await message_bus()->PublishAsync("telemetry/temperature", 
                TemperatureReading{ .value = temp });
            
            co_await async::sleep_for(std::chrono::seconds(5));
        }
    }

    double ReadTemperature() { return 23.5; }  // Simulated
    
    double threshold_ = 30.0;
    async::task monitor_task_;
};

// Register the module
NEXUS_MODULE_EXPORT(TemperatureMonitor)

classdef TemperatureMonitor < nexus.sdk.ModuleBase
    % Temperature monitoring module using transport-agnostic SDK
    
    properties (Constant)
        ModuleId = 'temperature-monitor'
        Version = '1.0.0'
    end
    
    properties (Access = private)
        threshold = 30.0
        timerObj
    end
    
    methods
        function obj = TemperatureMonitor()
            obj = obj@nexus.sdk.ModuleBase();
        end
        
        % Called by host during initialization
        function onInitialize(obj)
            obj.logger.info('Temperature monitor initializing');
            
            % Access capabilities granted in manifest
            capabilities = obj.moduleInfo.capabilities;
            obj.logger.info(sprintf('Granted capabilities: %s', ...
                strjoin(capabilities, ', ')));
        end
        
        % Called by host when module should start
        function start(obj, cancellationToken)
            start@nexus.sdk.ModuleBase(obj, cancellationToken);
            
            % Subscribe to temperature threshold commands
            obj.messageBus.subscribe('SetThresholdCommand', ...
                @(cmd) obj.handleThresholdCommand(cmd));
            
            % Start monitoring
            obj.timerObj = timer('Period', 5, ...
                'ExecutionMode', 'fixedRate', ...
                'TimerFcn', @(~,~) obj.checkTemperature());
            start(obj.timerObj);
        end
        
        % Called by host when module should stop
        function stop(obj, cancellationToken)
            if ~isempty(obj.timerObj)
                stop(obj.timerObj);
                delete(obj.timerObj);
            end
            stop@nexus.sdk.ModuleBase(obj, cancellationToken);
        end
    end
    
    methods (Access = private)
        function handleThresholdCommand(obj, command)
            obj.logger.info(sprintf('Threshold set to %.2f', command.threshold));
            obj.threshold = command.threshold;
        end
        
        function checkTemperature(obj)
            % Read temperature (simulated)
            temp = obj.readTemperature();
            
            % Create reading using SDK message base class
            reading = nexus.sdk.EventMessage();
            reading.value = temp;
            
            % Publish reading
            obj.messageBus.publish('telemetry/temperature', reading);
        end
        
        function temp = readTemperature(obj)
            temp = 20 + 10*rand();  % Simulated
        end
    end
end

% Message contracts
classdef SetThresholdCommand < nexus.sdk.RequestMessage
    properties
        threshold double
    end
end

classdef TemperatureReading < nexus.sdk.EventMessage
    properties
        value double
    end
end

// LabVIEW Temperature Monitor Module
// Uses Nexus SDK Client interfaces (transport-agnostic)

// Module Library: TemperatureMonitor.lvlib
// Properties:
//   - Name: "Temperature Monitor"
//   - Version: "1.0.0"

// Main VI: TemperatureMonitor.lvclass

// 1. Initialize.vi (Override from ModuleBase)
// Block Diagram:
//   - Call Parent Initialize
//   - Log "Temperature monitor initializing"
//   - Get Module Info from Context
//   - Extract Capabilities array
//   - Log "Granted capabilities: [list]"
//   - Set module ID = "temperature-monitor"

// 2. Start.vi (Override from ModuleBase)
// Block Diagram:
//   - Call Parent Start
//   - Subscribe to Commands:
//     * Topic Pattern: "SetThresholdCommand"
//     * Handler VI: HandleThresholdCommand.vi
//   - Start Temperature Loop:
//     * Create timed loop (5000ms period)
//     * Call CheckTemperature.vi

// 3. HandleThresholdCommand.vi
// Inputs: Command (SetThresholdCommand.ctl)
// Block Diagram:
//   - Extract threshold from command
//   - Update module threshold property
//   - Log "Threshold set to [value]"

// 4. CheckTemperature.vi
// Block Diagram:
//   - Read temperature (simulated)
//   - Create TemperatureReading:
//     * Use EventMessage base class
//     * Set value field
//   - Publish to "telemetry/temperature"

// Message Type Definitions:
// SetThresholdCommand.ctl (inherits RequestMessage.ctl)
// - threshold (DBL)

// TemperatureReading.ctl (inherits EventMessage.ctl)
// - value (DBL)

// Key Points:
// - All transport handled by host
// - Use SDK base classes for messages
// - Module only implements business logic
// - No knowledge of gRPC or other transport

Understanding Capabilities and Priority-Based Routing

Capabilities are security permissions defined in the manifest file, not in your module code. This design provides:

Deployment Flexibility - Same module binary can have different permissions in different environments
Security by Default - Modules have no permissions unless explicitly granted
Runtime Inspection - Modules can check their granted capabilities at runtime
Clean Architecture - Security concerns separated from business logic

Priority-Based Capability Routing

When multiple modules provide the same capability, the priority field determines routing:

Multiple Providers - Several modules can offer the same capability with different priority levels
Caller Requirements - Callers can specify minimum priority requirements (e.g., "I need READ_SENSOR with priority ≥ 200")
Smart Routing - The host selects the lowest-priority module that still meets the requirement
Fallback Support - If a high-priority module fails, the host can route to lower-priority alternatives

# Example: Multiple modules providing READ_SENSOR capability
modules:
  - id: "high-precision-sensor"
    capabilities: ["READ_SENSOR"]
    priority: 900  # High-quality, expensive sensor
    
  - id: "standard-sensor"
    capabilities: ["READ_SENSOR"]
    priority: 500  # Standard quality
    
  - id: "backup-sensor"
    capabilities: ["READ_SENSOR"]
    priority: 100  # Low-quality fallback

# Caller requests:
# - Priority 50: Routes to backup-sensor (100 ≥ 50)
# - Priority 200: Routes to standard-sensor (500 ≥ 200)
# - Priority 950: No module available (900 < 950)

Using Capability-Based Routing in Code

The SDK provides APIs to leverage capability routing:

// Request service by capability with minimum priority
var response = await MessageBus.RequestByCapabilityAsync(
    capability: "READ_SENSOR",
    request: new SensorRequest { SensorId = "temp1" },
    minimumPriority: 800,  // Require high-quality sensor
    timeout: TimeSpan.FromSeconds(5)
);

// Check capability availability before requesting
if (await MessageBus.IsCapabilityAvailableAsync("WRITE_PLC_DATA", minimumPriority: 500))
{
    // Safe to make the request
}

// Discover available providers
var providers = await MessageBus.GetCapabilityProvidersAsync("READ_SENSOR");
foreach (var provider in providers.OrderByDescending(p => p.Priority))
{
    Logger.LogInformation("{Name}: Priority {Priority}, Healthy: {Healthy}",
        provider.ModuleName, provider.Priority, provider.IsHealthy);
}

// Get only high-priority providers (e.g., for critical operations)
var criticalProviders = await MessageBus.GetCapabilityProvidersAsync(
    "READ_SENSOR", 
    minimumPriority: 700
);

This enables sophisticated patterns like quality-of-service tiers, graceful degradation, and cost optimization.

3. Build Your Module

dotnet build -c Release

# Create package
python -m build

# Or for development
pip install -e .

# Using CMake
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Or using make directly
make release

% No build step required for MATLAB
% Just ensure all files are in the module directory:
% - TemperatureMonitor.m (main class)
% - SetThresholdCommand.m
% - TemperatureReading.m

% Build steps in LabVIEW:
% 1. Open project in LabVIEW
% 2. Right-click Build Specifications
% 3. Select "New > Packed Library"
% 4. Configure:
%    - Source Files: Add module VIs
%    - Destinations: Set output path
% 5. Build

4. Deploy to Nexus Host

Manifest File Naming

The manifest file can have any name (e.g., nexus-manifest.yaml, production.yaml, dev-config.yaml):

If named nexus-manifest.yaml in the current directory, Nexus will use it by default
For any other name or location, use the --manifest argument when starting Nexus
This allows you to maintain multiple configurations (dev, staging, production)

Copy your module DLL to the host's modules/ directory