This package implements S/IP, the Sercos Internet Protocol for accessing data in Sercos devices, in go.
Supported services:
- TCP Ping to S/IP ping the device.
- TCP ReadEverything, ReadDescription, ReadOnlyData, ReadDataState for reading parameter data
- TCP WriteData for writing parameter data
- UDP Browse to browse for devices supporting the S/IP protocol.
- UDP SetIP and Identify to set the IP of a S/IP device or enable the identify signal on the device.
To install the gosip CLI tool into your Go toolchain, run:
go install github.com/philippseith/gosip/cmd/gosip@latestBefore tagging a CLI release, update cmd/gosip/go.mod to require a published root-library revision that contains the nested-module boundary. CLI releases use the module-directory prefix cmd/gosip/vX.Y.Z; for example, tag cmd/gosip/v0.1.0 to install with @v0.1.0. Library releases remain tagged vX.Y.Z.
The CLI supports a simple TCP ping check as well as UDP broadcast helpers for identification and network configuration.
To ping a device at its S/IP address:
gosip --address 192.168.1.50:35021 pingThe --address (-a) flag accepts a host or IP without a port; it defaults to the S/IP port 35021. Specify host:port to use a different port.
To read the full data set for an IDN, including metadata and values:
gosip --address 192.168.1.50:35021 readeverything --idn S-0-0095.0.0To read only the raw data bytes of an IDN:
gosip --address 192.168.1.50:35021 readonlydata --idn 0x100ARead output includes formatted values and spaced raw bytes. Long values wrap to the terminal width; wrapped raw rows show hexadecimal byte offsets, and wrapped formatted rows show decimal element indexes. Indexes are omitted when values fit on one row.
Formatted writes accept values as printed by readonlydata, with list elements separated by spaces. To write raw parameter data as a hexadecimal byte string, use --raw:
gosip --address 192.168.1.50:35021 writedata --idn S-0-0095.0.0 --raw --data 00112233To identify a device on a specific network interface:
gosip identify --interface eth0 --node 00:11:22:33:44:55To configure the IPv4 address of a device on that same interface:
gosip setip --interface eth0 --node 00:11:22:33:44:55 --ip 192.168.1.100 --gateway 192.168.1.1 --persistThe --interface flag selects the local NIC used for the broadcast, and --node is the device node identifier to target.
Running gosip without a command in a terminal opens the read/write prompt. At gosip>, use a host[:port] (or address host[:port]) to switch the S/IP target; a missing port defaults to 35021. Use b [interface] to browse devices, choosing an interface if omitted. Up and Down recall up to 500 in-memory lines; Left/Right/Home/End move the cursor, Delete and Backspace edit at the cursor, and Ctrl-A/B/E/F provide cursor movement. Bracketed terminal paste inserts the pasted text as one line, converting line breaks and tabs to spaces. History is separate for the gosip> and idn> prompts and is not saved to disk.
Example session:
Enter: [command] IDN, e.g. ro S-0-0032.0.0. Without command, re is used.
re, r readeverything read description, data state and data of an IDN
ro readonlydata read only the data of an IDN
rd readdescription read only the description of an IDN
rs readdatastate read only the data state of an IDN
w write write formatted data: w IDN value [value...]
wr write raw write raw hex bytes: wr IDN 0a1b2c3d
a address set the target S/IP address: a host[:port]
b browse list devices answering a UDP Browse: b [interface]; without interface, choose one
s status show the negotiated BusyTimeout and LeaseTimeout
h, ? help show this help
q quit quit the prompt
Type h, ?, or help to show this help. q, quit, Esc, or Ctrl-D quits. Up/Down recall history; cursor keys edit; bracketed paste inserts text.
gosip> a 192.168.112.34
Address set to 192.168.112.34:35021
gosip> r s30
IDN: S-0-0030.0.0
ValidElements: 0x0047 (DataState|Name|Attribute|Data)
DataState: 0x0000
Attribute: 0x70440001
Name: Electronic type plate DEVICE: Manufacturer software version
MaxListLength: 56
DataLength: 25
Data: FWA-XD1-AXS-V-0702N-NN-00
Data (raw): 46 57 41 2d 58 44 31 2d 41 58 53 2d 56 2d 30 37 30 32 4e 2d 4e 4e 2d 30 30
gosip>
Run gosip mcp to expose the CLI operations as MCP tools over standard input and output.
- Pass
addressin every device-tool request (an IPv4 address with an optional port, default 35021);gosip mcp --addressis rejected. - The address is parsed strictly: dotted-decimal IPv4 without leading zeros, optionally followed by
:port; host names, IPv6 and an empty host or port are rejected, and every spelling of the same endpoint shares one client. - At most 1024 clients are cached; beyond that the least recently used idle client is closed, and if all are in use the request fails.
- Tool requests may only connect to port 35021; pass
gosip mcp --allow-port <port>(repeatable or comma separated) to permit additional ports, for example a simulator on another port. - A request may only connect to a device that answers a UDP Browse sent on the one interface the operating system routes to its address; this is checked before the first connection and again whenever an idle or closed client was removed. An address is always checked the first time. After a failed check, an address that has already failed is not checked again for 1 second, doubling after each further consecutive failure (of any address) up to 5 minutes, and a successful check resets this; such a request fails immediately without a broadcast. Addresses that did not fail before and addresses that already have a client are not affected.
- Devices behind a router and devices or simulators that do not answer a UDP Browse (for example the TCP-only
sipserver) needgosip mcp --allow-all-hosts, which disables only this check; the address must still be an IPv4 literal. - The tools are
ping,readeverything,readonlydata,readdescription,readdatastate,writedata,browse,identify, andsetip. Results are structured JSON. - The server keeps one client per normalized device address and closes idle clients after twice their negotiated lease timeout (20 seconds before a lease is negotiated, unless
--leasetimeoutoverrides it). - Broadcast tools use UDP;
browsewithoutinterfacelists available interfaces, whileidentifyandsetiprequire it. Theirlistenduration defaults to 3 seconds and is clamped to 10 seconds. A call collects at most 1024 responses and errors together; if more arrive, listening stops early and the result has"truncated": true. - Text that devices supply (display and host names, IDN names and units, text data) is untrusted.
gosipreplaces control characters and invalid UTF-8 in it with.before printing it to a terminal; the MCP server returns it unchanged, but the server instructions, the tool descriptions and the output schemas mark it as untrusted data that the model must not treat as instructions.
gosip mcp speaks MCP over stdio. The checked-in project configs run go run ./cmd/gosip mcp, so Go must be on PATH and the client must start the server from the repository root; the first run may download modules. Add flags such as --allow-port 35022 or --allow-all-hosts after mcp only when needed. The clients also support user-level config, but those entries should use an installed gosip binary rather than this repository-relative command.
This repository includes ready-to-use project configs for every client listed here, including OMP and Pi. Try it out!
| Client | Project file | Entry |
|---|---|---|
| Claude Code, Copilot CLI | .mcp.json |
{"mcpServers": {"gosip": {"command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
| Cursor | .cursor/mcp.json |
{"mcpServers": {"gosip": {"command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
| Gemini CLI | .gemini/settings.json |
{"mcpServers": {"gosip": {"command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
| VS Code | .vscode/mcp.json |
{"servers": {"gosip": {"type": "stdio", "command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
| Zed | .zed/settings.json |
{"context_servers": {"gosip": {"command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
| opencode | opencode.json |
{"mcp": {"gosip": {"type": "local", "command": ["go", "run", "./cmd/gosip", "mcp"]}}} |
| OMP | .omp/mcp.json |
{"mcpServers": {"gosip": {"type": "stdio", "command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
| Pi | .pi/mcp.json |
{"mcpServers": {"gosip": {"command": "go", "args": ["run", "./cmd/gosip", "mcp"]}}} |
Codex reads .codex/config.toml in trusted projects:
[mcp_servers.gosip]
command = "go"
args = ["run", "./cmd/gosip", "mcp"]Merge the entry into an existing file instead of replacing it. Pi reads .pi/mcp.json only after you trust the project, and by default makes MCP tools reachable only through its codemode tool; add "exposure": "direct" to the gosip entry to declare the tools to the model directly. Clients ask for approval of project-scoped servers and tool calls; writedata and setip change device state, so review each call.
sercos.ParseData(attr, s) reverses Data.String(attr). sercos.ParseDatas(attr, ss) parses the elements returned by Data.Strings(attr) and concatenates their bytes. sercos.Data also implements fmt.Scanner for b, u, d, x, X, s, i, f, and t.
For IDNs, compact S30 and s30 forms parse as S-0-0030.
func parseAndScan() error {
attr := sercos.Attribute(0x03110001)
data, err := sercos.ParseData(attr, "1.000")
if err != nil {
return err
}
var scanned sercos.Data
if _, err = fmt.Sscanf("0b0000.0000.0000.0010", "%b", &scanned); err != nil {
return err
}
fmt.Printf("parsed=%v scanned=%v\n", []byte(data), []byte(scanned))
return nil
}For b, u, d, x, X, i, and f, scanning reuses an existing Data length of 1, 2, 4, or 8 bytes; use an empty Data to infer the length from the token. s and t ignore the current length. fmt width keeps its standard meaning as a maximum input-rune count, not a byte length.
Per the Sercos IDN parameter model, this implementation enforces a maximum of 65535 (0xFFFF) bytes on all variable-length PDU fields:
| Field | PDU(s) |
|---|---|
| Data | ReadEverything, ReadOnlyData, WriteData |
| Name | ReadEverything, ReadDescription |
| Unit | ReadEverything, ReadDescription |
| DisplayName, HostName | Browse |
| NoMessageTypes | Connect |
Responses advertising larger values are rejected with an error.
ext.AttachSIPSource adds a S/IP bridge to a caller-owned gliderlabs/ssh server. It installs a net.Listener that accepts streams from SSH direct-tcpip channels and calls sip.Serve for each channel. No TCP listener or destination dial is created.
The caller configures host keys and authentication directly on gliderssh.Server. Authentication is optional to AttachSIPSource: gliderlabs permits unauthenticated SSH when no authentication handlers are configured. Use that only on a trusted network or listener. The factory can reject destinations, but TargetRequest.Username is not an authenticated identity unless server authentication is configured.
One SSH connection may hold at most ext.DefaultMaxChannelsPerConnection (32) open S/IP channels; further direct-tcpip channels are rejected with ResourceShortage until one closes. Every channel runs its own sip.Serve loop, so the sip.WithMaxConnections limit does not bound the connection as a whole. Pass ext.WithMaxChannelsPerConnection(n) as the last argument of AttachSIPSource to change the limit. gliderssh.Server.IdleTimeout and MaxTimeout are zero (unlimited) by default; set them if idle SSH connections must not live forever.
package main
import (
"context"
"errors"
"net"
"os"
gliderssh "github.com/gliderlabs/ssh"
"github.com/philippseith/gosip/ext"
"github.com/philippseith/gosip/sip"
cryptossh "golang.org/x/crypto/ssh"
)
func serveSSH(ctx context.Context, source sip.SyncClient) error {
hostKeyPEM, err := os.ReadFile("ssh_host_ed25519")
if err != nil {
return err
}
hostSigner, err := cryptossh.ParsePrivateKey(hostKeyPEM)
if err != nil {
return err
}
server := &gliderssh.Server{
HostSigners: []gliderssh.Signer{hostSigner},
PasswordHandler: func(ctx gliderssh.Context, password string) bool {
return ctx.Err() == nil && ctx.User() == "operator" && password == os.Getenv("SSH_PASSWORD")
},
}
mux := sip.NewMux(source)
factory := func(ctx context.Context, target ext.TargetRequest) (sip.SyncClient, error) {
if err := ctx.Err(); err != nil {
return nil, err
}
if target.Username != "operator" || target.Host != "127.0.0.1" || target.Port != 35021 {
return nil, errors.New("forwarding target is not allowed")
}
return mux, nil
}
if err := ext.AttachSIPSource(ctx, server, factory, []sip.ConnOption{sip.WithBusyTimeout(3000)}); err != nil {
return err
}
sshListener, err := net.Listen("tcp", "127.0.0.1:2222")
if err != nil {
return err
}
defer sshListener.Close()
return server.Serve(sshListener)
}The factory is called concurrently and should be safe for concurrent use. Its parameter is the standard context.Context, derived from the SSH connection and canceled when that connection or the attachment stops. gliderssh.Context is the richer context supplied to gliderlabs callbacks: it embeds context.Context and adds SSH-specific metadata and synchronization methods. The factory receives the standard interface for decoupling; TargetRequest carries the requested username and forwarding destination.
The installer preserves the server's other channel, request, and subsystem handlers, including gliderlabs' default session handler when no channel map was supplied. It reserves direct-tcpip; attaching to a server with an existing handler for that type returns an error. SCP/SFTP can use configured session or subsystem handlers; a TFTP service needs a UDP gateway. The example's 127.0.0.1:35021 is a logical SSH target, not a server-side TCP listener: ssh -p 2222 -N -L 35021:127.0.0.1:35021 operator@127.0.0.1 sends each channel directly to its factory-selected S/IP service.
