goroslib

goroslib is a library in pure Go that allows to build clients (nodes) for the Robot Operating System (ROS).

The Robot Operating System (ROS) is a project that provides a specification to make multiple programs communicate with each other over time, exchanging structured data with topics, services, actions and parameters. It was conceived to link sensors, algorithms and actuators in unmanned ground vehicles (UGVs) and robots, but it is not bounded to the robot world and can be used anywhere there's the need of building streams of data (for example in video processing).

Features:

• publish and subscribe to topics with TCP or UDP
• provide and call services
• provide and call actions
• provide and call simple actions
• get and set parameters
• support namespaces and relative topics
• support IPv6 (stateful addresses only)
• support time API
• compilation of .msg files is not necessary, message definitions are extracted from code
• compile or cross-compile for all Go supported OSs (Linux, Windows, Mac OS X) and architectures
• examples provided for every feature, comprehensive test suite, continuous integration

Table of contents

• Installation
• API Documentation
• FAQs
  • Comparison with other libraries
  • Full list of features
  • Standard messages, services and actions
  • Custom messages, services and actions
  • Import existing messages, services and actions
  • Compile a node for another operating system
  • Edit the library
• Specifications
• Links

Installation

1. Install Go ≥ 1.21.

2. Create an empty folder, open a terminal in it and initialize the Go modules system:

   go mod init main
   

3. Download one of the example files and place it in the folder:

   • subscriber
   • subscriber-custom
   • subscriber-udp
   • subscriber-ipv6
   • publisher
   • publisher-custom
   • serviceclient
   • serviceprovider
   • simpleactionclient
   • simpleactionserver
   • param-set-get
   • cluster-info

4. Compile and run (a ROS master must be already running in the background)

   go run name-of-the-go-file.go
   

API Documentation

Click to open the API Documentation

FAQs

Comparison with other libraries

goroslib vs official C++/Python libraries

The official project provides libraries to write nodes in C++ and Python, but they require the download of over 1GB of data and work only with a fixed buildchain. This library allows to write lightweight nodes that can be built with the standard Go compiler, do not need any runtime library and have a size of some megabytes. Another advantage lies in the possibility of compiling nodes for all the Golang supported operating systems (Linux, Windows, Mac OS X, etc) and architectures.

goroslib vs rosgo

rosgo is currently unmaintained; furthermore, it requires compilation of .msg files, doesn't support UDP, doesn't support actions, doesn't support simulated clocks.

Full list of features

Current and missing features are described in the FEATURES document.

Standard messages, services and actions

This library provides most of the standard messages, services and actions in the folder pkg/msgs:

package	documentation	repository
ackermann_msgs	link	link
actionlib	link	link
actionlib_msgs	link	link
audio_common_msgs	link	link
control_msgs	link	link
diagnostic_msgs	link	link
geometry_msgs	link	link
geographic_msgs	link	link
mavros_msgs	link	link
nav_msgs	link	link
rosgraph_msgs	link	link
sensor_msgs	link	link
shape_msgs	link	link
sound_play	link	link
std_msgs	link	link
std_srvs	link	link
stereo_msgs	link	link
tf	link	link
tf2_msgs	link	link
trajectory_msgs	link	link
uuid_msgs	link	link
velodyne_msgs	link	link
vision_msgs	link	link
visualization_msgs	link	link

Custom messages, services and actions

To define custom messages, the standard ROS C++/Python libraries require .msg files in this format:

bool field1
int32 field2

This library doesn't require any .msg file, it is enough to write Go structures in this format:

import (
    "github.com/bluenviron/goroslib/v2/pkg/msgs"
)

type MessageName struct {
    msg.Package `ros:"my_package"`
    Field1 bool
    Field2 int32
}

The name of the message is taken from the name of the struct (in this case, MessageName), but it can be overridden by adding the msg.Name field:

type MessageName struct {
    msg.Package `ros:"my_package"`
    msg.Name `ros:"my_message_name"`
    Field1 bool
    Field2 int32
}

The type of a field can be one of the following:

• one of the primitive field types: bool, int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, float64, string, time.Time, time.Duration

• another standard or custom message

The name of a field must be in CamelCase, and is converted to snake_case when interacting with C++/Python nodes. If this conversion is not possible, the tag rosname can be used to override the field name:

type MessageName struct {
    msg.Package `ros:"my_package"`
    Field bool  `rosname:"FIELD"`
}

Services in this format:

uint32 input
---
uint32 output

Are equivalent to Go structures in this format:

type ServiceNameReq struct {
    Input uint32
}

type ServiceNameRes struct {
	Output uint32
}

type ServiceName struct {
	msg.Package `ros:"my_package"`
	ServiceNameReq
	ServiceNameRes
}

Actions in this format:

uint32 goal
---
uint32 result
---
uint32 feedback

Are equivalent to Go structures in this format:

type ActionNameGoal struct {
	Goal uint32
}

type ActionNameResult struct {
	Result uint32
}

type ActionNameFeedback struct {
	Feedback uint32
}

type ActionName struct {
	msg.Package `ros:"my_package"`
	ActionNameGoal
	ActionNameResult
	ActionNameFeedback
}

Import existing messages, services and actions

You can convert existing .msg files into their equivalent Go structures by using the msg-import tool:

go install github.com/bluenviron/goroslib/v2/cmd/msg-import@latest
msg-import --rospackage=my_package mymessage.msg > mymessage.go

You can convert existing .srv files into their equivalent Go structures by using the srv-import tool:

go install github.com/bluenviron/goroslib/v2/cmd/srv-import@latest
srv-import --rospackage=my_package myservice.srv > myservice.go

You can convert existing .action files into their equivalent Go structures by using the action-import tool:

go install github.com/bluenviron/goroslib/v2/cmd/action-import@latest
action-import --rospackage=my_package myaction.action > myaction.go

To convert a whole ROS package to Go, you can use the package-import tool:

go install github.com/bluenviron/goroslib/v2/cmd/package-import@latest
package-import <path-to-ros-package>

Compile a node for another operating system

To compile a node for another OS, it's enough to follow the standard Golang procedure to cross-compile, that consists in setting the GOOS and GOARCH environment variables according to the target machine. For instance, to build a node for Windows from another OS, run:

GOOS=windows GOARCH=amd64 go build -o node.exe name-of-source-file.go

Edit the library

If you want to hack the library and test the results, unit tests can be launched with:

make test

Specifications

name	area
Technical overview	general
Implementing client libraries	general
Names	general
Actionlib	action lib
Actionlib detailed description	action lib
Master API	API
Parameter server API	API
Slave API	API
Connection header	protocol
TCPROS	protocol
UDPROS	protocol
Wireshark dissector	protocol
Golang project layout	project layout

Links

Other Go libraries

• rosgo (v1)
• rclgo (v2)

Other non-Go libraries

• official library (v1) (C++) (documentation)
• official library (v1) (Python)
• cros (v1) (C)
• foxglove/ros1 (v1) (TypeScript)
• awesome ros2 (v2) (misc)
• foxglove/ros2 (v2) (TypeScript)