github.com/Netsocs-Team/driver.sdk_go


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

Documentation

Netsocs Driver SDK for Go

Go Version License Documentation

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

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

API Reference

Advanced Topics

Integration Guides

๐Ÿ—๏ธ 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

๐Ÿท๏ธ 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.