Netsocs Driver SDK for Go

The official Go SDK for developing Netsocs IoT device drivers. Build robust, production-ready drivers for cameras, access control systems, alarm panels, sensors, and custom IoT devices.

🚀 Quick Start

# Install the SDK
go get github.com/Netsocs-Team/driver.sdk_go

# Create a new driver from template
./scripts/new-driver.ps1 -Name my-driver -Module github.com/myorg/my-driver

# Build and run
cd my-driver
go mod tidy
go build -o my-driver
./my-driver

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Architecture Overview
• Quick Example
• Documentation
• Driver Template
• Examples
• Testing
• Contributing
• License

✨ Features

Core SDK Capabilities

• 25+ Built-in Object Types: Sensors, cameras, locks, alarms, GPS trackers, and more
• 70+ Configuration Handlers: Pre-defined handlers for common device operations
• Event System: Dispatch events with images, videos, and custom properties
• State Management: Real-time state updates and attribute management
• Connection Pooling: Efficient device connection management
• Type Safety: Leverages Go's type system for robust development

Supported Integrations

• Video Surveillance: IP cameras, NVRs, DVRs (Hikvision, Dahua, ONVIF)
• Access Control: Biometric readers, card readers, door controllers
• Alarm Systems: Security panels, zones, partitions
• Environmental Monitoring: Temperature, humidity, motion sensors
• Cloud Services: AWS SQS, webhooks, REST APIs

📚 Prerequisites

• Go 1.21+: Download Go
• Git: For version control and dependency management
• Netsocs Platform Access: Driver credentials and platform endpoint
• Device Documentation: API specifications for target devices

🔧 Installation

Method 1: Using Go Modules (Recommended)

# Initialize your driver project
mkdir my-netsocs-driver
cd my-netsocs-driver
go mod init github.com/myorg/my-netsocs-driver

# Install the SDK
go get github.com/Netsocs-Team/driver.sdk_go

Method 2: Using the Template

# Clone the SDK repository
git clone https://github.com/Netsocs-Team/driver.sdk_go.git
cd driver.sdk_go

# Create a new driver from template
./scripts/new-driver.ps1 -Name my-driver -Module github.com/myorg/my-driver

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Netsocs Platform                         │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │   DriverHub     │    │   Web UI        │                │
│  │   (WebSocket)   │    │   (Actions)     │                │
│  └─────────┬───────┘    └─────────────────┘                │
└───────────┼─────────────────────────────────────────────────┘
            │ Configuration Requests
            │ State Updates & Events
            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Your Driver                              │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │ Config Handlers │    │    Objects      │                │
│  │ (Ping, Channels,│    │ (Sensors, Cams, │                │
│  │  Users, etc.)   │    │  Locks, etc.)   │                │
│  └─────────┬───────┘    └─────────┬───────┘                │
│            │                      │                        │
│            └──────────┬───────────┘                        │
│                       │                                    │
│  ┌─────────────────────▼─────────────────────┐              │
│  │           Device Manager                  │              │
│  │        (Connection Pooling)               │              │
│  └─────────────────────┬─────────────────────┘              │
└─────────────────────────┼─────────────────────────────────────┘
                          │ HTTP/TCP/WebSocket/SDK
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                Physical Devices                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Camera    │  │ Access Ctrl │  │ Alarm Panel │        │
│  │    NVR      │  │   Reader    │  │   Sensors   │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘

Key Components

1. SDK Client: Manages communication with the Netsocs platform
2. Configuration Handlers: Process platform requests for device operations
3. Objects: Represent devices and their capabilities (states, actions)
4. Device Manager: Handles connection pooling and device communication
5. Events: Notify the platform of significant occurrences

🎯 Quick Example

Here's a minimal temperature sensor driver:

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/Netsocs-Team/driver.sdk_go/pkg/client"
    "github.com/Netsocs-Team/driver.sdk_go/pkg/config"
    "github.com/Netsocs-Team/driver.sdk_go/pkg/objects"
)

func main() {
    // Initialize SDK client
    c, err := client.New()
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    // Register configuration handlers
    c.AddConfigHandler(config.ACTION_PING_DEVICE, handlePing)
    c.AddConfigHandler(config.REQUEST_CREATE_OBJECTS, handleCreateObjects(c))

    // Start listening for platform requests
    log.Println("Driver ready, listening for requests...")
    c.ListenConfig()
}

func handlePing(msg config.HandlerValue) (interface{}, error) {
    // Test device connectivity
    return map[string]interface{}{
        "status": true,
        "msg":    "Device is online",
    }, nil
}

func handleCreateObjects(c *client.NetsocsDriverClient) config.FuncConfigHandler {
    return func(msg config.HandlerValue) (interface{}, error) {
        // Create temperature sensor
        sensor := objects.NewSensorObject(objects.NewSensorObjectParams{
            Metadata: objects.ObjectMetadata{
                ObjectID: "temp_sensor_01",
                Name:     "Living Room Temperature",
                Domain:   "temperature",
                DeviceID: msg.DeviceData.ID,
            },
            SetupFn: func(obj objects.RegistrableObject, oc objects.ObjectController) error {
                sensor := obj.(objects.SensorObject)
                sensor.SetSensorType(objects.SensorObjectTypeNumber)
                sensor.SetUnitOfMeasurement("°C")
                sensor.SetState(objects.SENSOR_STATE_MEASUREMENT)
                sensor.SetValue("20.0")
                
                // Start temperature updates
                go updateTemperature(sensor)
                return nil
            },
        })

        // Register with platform
        return nil, c.RegisterObject(sensor)
    }
}

func updateTemperature(sensor objects.SensorObject) {
    ticker := time.NewTicker(10 * time.Second)
    defer ticker.Stop()
    
    temperature := 20.0
    for range ticker.C {
        temperature += (float64(time.Now().Unix()%3) - 1) * 0.5
        sensor.SetValue(fmt.Sprintf("%.1f", temperature))
    }
}

📖 Documentation

Getting Started

• Installation Guide
• Your First Driver
• Understanding Objects
• Configuration Handlers

API Reference

• Client API
• Object Types
  • Sensor Objects
  • Switch Objects
  • Video Channel Objects
  • Lock Objects
  • Alarm Panel Objects
• Configuration System
• Events

Advanced Topics

• Device Connection Management
• Event System Deep Dive
• State Management
• Error Handling
• Performance Optimization
• Security Best Practices

Integration Guides

• IP Camera Integration
• Access Control Systems
• Alarm Systems
• Cloud Services

🏗️ Driver Template

The SDK includes a production-ready template with:

template/
├── main.go                      # Entry point with client initialization
├── go.mod                       # Go module definition
├── driver.netsocs.json.example  # Configuration template
├── config/
│   └── handlers.go             # Configuration request handlers
├── devices/
│   └── device_manager.go       # Device connection pooling
└── objects/
    ├── sensor_example.go       # Example sensor implementation
    └── switch_example.go       # Example switch implementation

Using the Template

# Generate a new driver
./scripts/new-driver.ps1 -Name my-camera-driver -Module github.com/myorg/my-camera-driver

# Customize for your integration
cd my-camera-driver
# Edit config/handlers.go - implement your device API calls
# Edit objects/ - create objects for your device types
# Edit driver.netsocs.json - add your credentials

# Build and test
go mod tidy
go test ./...
go build -o my-camera-driver
./my-camera-driver

🔍 Examples

Video Surveillance Driver

// Register camera objects
camera := objects.NewVideoChannelObject(objects.NewVideoChannelObjectProps{
    Metadata: objects.ObjectMetadata{
        ObjectID: "camera_ch1",
        Name:     "Front Entrance Camera",
        Domain:   "camera",
        DeviceID: "nvr_001",
    },
    StreamID:    "rtsp://192.168.1.10:554/stream1",
    VideoEngine: "video_engine_01",
    PTZ:         true,
    SnapshotFn: func(vc objects.VideoChannelObject, oc objects.ObjectController,
                     payload objects.SnapshotActionPayload) (string, error) {
        // Capture and upload snapshot
        imageURL, err := captureSnapshot(vc.GetMetadata().ObjectID)
        return imageURL, err
    },
})

Access Control Driver

// Register reader object
reader := objects.NewReaderObject(objects.NewReaderObjectParams{
    Metadata: objects.ObjectMetadata{
        ObjectID: "reader_main_entrance",
        Name:     "Main Entrance Reader",
        Domain:   "access_control",
        DeviceID: "ac_panel_001",
    },
    SupportedCredentialTypes: []string{"card", "face", "fingerprint"},
})

// Dispatch access events
eventData := objects.Event{
    ObjectIDs: []string{"reader_main_entrance"},
    Properties: map[string]string{
        "user_id":     "12345",
        "credential":  "card",
        "result":      "granted",
        "door_id":     "main_door",
    },
}
client.DispatchEvent("access_control", "access_granted", eventData)

Alarm System Driver

// Register alarm panel
panel := objects.NewAlarmPanelObject(objects.NewAlarmPanelObjectProps{
    Metadata: objects.ObjectMetadata{
        ObjectID: "alarm_panel_main",
        Name:     "Main Security Panel",
        Domain:   "alarm",
        DeviceID: "panel_001",
    },
})

// Register zone sensors
for _, zone := range zones {
    sensor := objects.NewSensorObject(objects.NewSensorObjectParams{
        Metadata: objects.ObjectMetadata{
            ObjectID: fmt.Sprintf("zone_%s", zone.ID),
            Name:     zone.Name,
            Domain:   "alarm",
            DeviceID: "panel_001",
            ParentID: "alarm_panel_main",
        },
    })
    client.RegisterObject(sensor)
}

🧪 Testing

Unit Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific package tests
go test ./pkg/objects

Integration Tests

# Test with mock device
go test -tags=integration ./tests/

# Test configuration handlers
go test ./config -run TestHandlers

Example Test

func TestPingHandler(t *testing.T) {
    handler := handlePingDevice(mockDeviceManager)
    
    msg := config.HandlerValue{
        DeviceData: config.DeviceData{
            IP:   "192.168.1.100",
            Port: 80,
        },
    }
    
    response, err := handler(msg)
    assert.NoError(t, err)
    
    result := response.(map[string]interface{})
    assert.True(t, result["status"].(bool))
}

🚀 Production Deployment

Building for Production

# Build with version information
go build -ldflags="-X main.Version=1.0.0" -o my-driver

# Cross-compile for different platforms
GOOS=linux GOARCH=amd64 go build -o my-driver-linux
GOOS=windows GOARCH=amd64 go build -o my-driver-windows.exe

Docker Deployment

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o driver .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/driver .
COPY driver.netsocs.json .
CMD ["./driver"]

Systemd Service (Linux)

[Unit]
Description=My Netsocs Driver
After=network.target

[Service]
Type=simple
User=netsocs
WorkingDirectory=/opt/my-driver
ExecStart=/opt/my-driver/my-driver
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/Netsocs-Team/driver.sdk_go.git
cd driver.sdk_go

# Install dependencies
go mod download

# Run tests
go test ./...

# Run linting
golangci-lint run

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: https://docs.netsocs.com
• GitHub Issues: Report bugs or request features
• Community: Join our developer community for discussions and support

🏷️ Version History

• v0.7.70: Latest stable release with enhanced object types and improved error handling
• v0.7.65: Added cloud service integration support
• v0.7.60: Performance improvements and bug fixes
• See CHANGELOG.md for complete version history

---

Ready to build your first driver? Start with our Installation Guide and follow the Quick Start Tutorial.