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.
# 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- Features
- Prerequisites
- Installation
- Architecture Overview
- Quick Example
- Documentation
- Driver Template
- Examples
- Testing
- Contributing
- License
- 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
- 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
- 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
# 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# 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โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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 โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- SDK Client: Manages communication with the Netsocs platform
- Configuration Handlers: Process platform requests for device operations
- Objects: Represent devices and their capabilities (states, actions)
- Device Manager: Handles connection pooling and device communication
- Events: Notify the platform of significant occurrences
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))
}
}- Device Connection Management
- Event System Deep Dive
- State Management
- Error Handling
- Performance Optimization
- Security Best Practices
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
# 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// 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
},
})// 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)// 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)
}# Run all tests
go test ./...
# Run tests with coverage
go test -cover ./...
# Run specific package tests
go test ./pkg/objects# Test with mock device
go test -tags=integration ./tests/
# Test configuration handlers
go test ./config -run TestHandlersfunc 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))
}# 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.exeFROM 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"][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.targetWe welcome contributions! Please see our Contributing Guide for details.
# 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 runThis project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: https://docs.netsocs.com
- GitHub Issues: Report bugs or request features
- Community: Join our developer community for discussions and support
- 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.