{"id":13413165,"url":"https://github.com/bluenviron/goroslib","last_synced_at":"2025-04-05T11:11:03.040Z","repository":{"id":41952574,"uuid":"234957700","full_name":"bluenviron/goroslib","owner":"bluenviron","description":"ROS client library for the Go programming language","archived":false,"fork":false,"pushed_at":"2024-05-08T22:38:24.000Z","size":1356,"stargazers_count":304,"open_issues_count":1,"forks_count":56,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-05-21T04:15:32.831Z","etag":null,"topics":["go","golang","robot-operating-system","ros","ros-industrial","ros-libraries","ros-melodic","ros-package","ugv"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluenviron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.buymeacoffee.com/aler9"]}},"created_at":"2020-01-19T20:02:35.000Z","updated_at":"2024-06-18T16:47:56.409Z","dependencies_parsed_at":"2023-10-11T23:19:42.649Z","dependency_job_id":"99ad912e-26c1-47fe-a365-75ec2c8c7016","html_url":"https://github.com/bluenviron/goroslib","commit_stats":null,"previous_names":["aler9/goroslib"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluenviron%2Fgoroslib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluenviron%2Fgoroslib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluenviron%2Fgoroslib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluenviron%2Fgoroslib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluenviron","download_url":"https://codeload.github.com/bluenviron/goroslib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","robot-operating-system","ros","ros-industrial","ros-libraries","ros-melodic","ros-package","ugv"],"created_at":"2024-07-30T20:01:34.365Z","updated_at":"2025-04-05T11:11:03.020Z","avatar_url":"https://github.com/bluenviron.png","language":"Go","funding_links":["https://www.buymeacoffee.com/aler9"],"categories":[],"sub_categories":[],"readme":"# goroslib\n\n[![Test](https://github.com/bluenviron/goroslib/actions/workflows/test.yml/badge.svg)](https://github.com/bluenviron/goroslib/actions/workflows/test.yml)\n[![Lint](https://github.com/bluenviron/goroslib/actions/workflows/lint.yml/badge.svg)](https://github.com/bluenviron/goroslib/actions/workflows/lint.yml)\n[![Msgs](https://github.com/bluenviron/goroslib/actions/workflows/msgs.yml/badge.svg)](https://github.com/bluenviron/goroslib/actions/workflows/msgs.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bluenviron/goroslib)](https://goreportcard.com/report/github.com/bluenviron/goroslib)\n[![CodeCov](https://codecov.io/gh/bluenviron/goroslib/branch/main/graph/badge.svg)](https://app.codecov.io/gh/bluenviron/goroslib/tree/main)\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/bluenviron/goroslib/v2)](https://pkg.go.dev/github.com/bluenviron/goroslib/v2#pkg-index)\n\ngoroslib is a library in pure Go that allows to build clients (nodes) for the Robot Operating System (ROS).\n\nThe 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).\n\nFeatures:\n\n* publish and subscribe to topics with TCP or UDP\n* provide and call services\n* provide and call actions\n* provide and call simple actions\n* get and set parameters\n* support namespaces and relative topics\n* support IPv6 (stateful addresses only)\n* support time API\n* compilation of `.msg` files is not necessary, message definitions are extracted from code\n* compile or cross-compile for all Go supported OSs (Linux, Windows, Mac OS X) and architectures\n* examples provided for every feature, comprehensive test suite, continuous integration\n\n## Table of contents\n\n* [Installation](#installation)\n* [API Documentation](#api-documentation)\n* [FAQs](#faqs)\n  * [Comparison with other libraries](#comparison-with-other-libraries)\n  * [Full list of features](#full-list-of-features)\n  * [Standard messages, services and actions](#standard-messages-services-and-actions)\n  * [Custom messages, services and actions](#custom-messages-services-and-actions)\n  * [Import existing messages, services and actions](#import-existing-messages-services-and-actions)\n  * [Compile a node for another operating system](#compile-a-node-for-another-operating-system)\n  * [Edit the library](#edit-the-library)\n* [Specifications](#specifications)\n* [Links](#links)\n\n## Installation\n\n1. Install Go \u0026ge; 1.21.\n\n2. Create an empty folder, open a terminal in it and initialize the Go modules system:\n\n   ```\n   go mod init main\n   ```\n\n3. Download one of the example files and place it in the folder:\n\n   * [subscriber](examples/subscriber/main.go)\n   * [subscriber-custom](examples/subscriber-custom/main.go)\n   * [subscriber-udp](examples/subscriber-udp/main.go)\n   * [subscriber-ipv6](examples/subscriber-ipv6/main.go)\n   * [publisher](examples/publisher/main.go)\n   * [publisher-custom](examples/publisher-custom/main.go)\n   * [serviceclient](examples/serviceclient/main.go)\n   * [serviceprovider](examples/serviceprovider/main.go)\n   * [simpleactionclient](examples/simpleactionclient/main.go)\n   * [simpleactionserver](examples/simpleactionserver/main.go)\n   * [param-set-get](examples/param-set-get/main.go)\n   * [cluster-info](examples/cluster-info/main.go)\n\n4. Compile and run (a ROS master must be already running in the background)\n\n   ```\n   go run name-of-the-go-file.go\n   ```\n\n## API Documentation\n\n[Click to open the API Documentation](https://pkg.go.dev/github.com/bluenviron/goroslib/v2#pkg-index)\n\n## FAQs\n\n### Comparison with other libraries\n\n#### goroslib vs official C++/Python libraries\n\nThe 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.\n\n#### goroslib vs rosgo\n\nrosgo is currently unmaintained; furthermore, it requires compilation of `.msg` files, doesn't support UDP, doesn't support actions, doesn't support simulated clocks.\n\n### Full list of features\n\nCurrent and missing features are [described in the FEATURES document](FEATURES.md).\n\n### Standard messages, services and actions\n\nThis library provides most of the standard messages, services and actions in the folder `pkg/msgs`:\n\n|package|documentation|repository|\n|-------|-------------|----------|\n|ackermann_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/ackermann_msgs)|[link](https://github.com/ros-drivers/ackermann_msgs)|\n|actionlib|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/actionlib)|[link](https://github.com/ros/actionlib)|\n|actionlib_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/actionlib_msgs)|[link](https://github.com/ros/common_msgs)|\n|audio_common_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/audio_common_msgs)|[link](https://github.com/ros-drivers/audio_common)|\n|control_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/control_msgs)|[link](https://github.com/ros-controls/control_msgs)|\n|diagnostic_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/diagnostic_msgs)|[link](https://github.com/ros/common_msgs)|\n|geometry_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/geometry_msgs)|[link](https://github.com/ros/common_msgs)|\n|geographic_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/geographic_msgs)|[link](https://github.com/ros-geographic-info/geographic_info)|\n|mavros_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/mavros_msgs)|[link](https://github.com/mavlink/mavros)|\n|nav_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/nav_msgs)|[link](https://github.com/ros/common_msgs)|\n|rosgraph_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/rosgraph_msgs)|[link](https://github.com/ros/ros_comm_msgs)|\n|sensor_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/sensor_msgs)|[link](https://github.com/ros/common_msgs)|\n|shape_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/shape_msgs)|[link](https://github.com/ros/common_msgs)|\n|sound_play|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/sound_play)|[link](https://github.com/ros-drivers/audio_common)|\n|std_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/std_msgs)|[link](https://github.com/ros/std_msgs)|\n|std_srvs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/std_srvs)|[link](https://github.com/ros/ros_comm_msgs)|\n|stereo_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/stereo_msgs)|[link](https://github.com/ros/common_msgs)|\n|tf|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/tf)|[link](https://github.com/ros/geometry)|\n|tf2_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/tf2_msgs)|[link](https://github.com/ros/geometry2)|\n|trajectory_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/trajectory_msgs)|[link](https://github.com/ros/common_msgs)|\n|uuid_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/uuid_msgs)|[link](https://github.com/ros-geographic-info/unique_identifier)|\n|velodyne_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/velodyne_msgs)|[link](https://github.com/ros-drivers/velodyne)|\n|vision_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/vision_msgs)|[link](https://github.com/ros-perception/vision_msgs)|\n|visualization_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/visualization_msgs)|[link](https://github.com/ros/common_msgs)|\n\n### Custom messages, services and actions\n\nTo define custom messages, the standard ROS C++/Python libraries require `.msg` files in this format:\n\n```\nbool field1\nint32 field2\n```\n\nThis library doesn't require any `.msg` file, it is enough to write Go structures in this format:\n\n```go\nimport (\n    \"github.com/bluenviron/goroslib/v2/pkg/msgs\"\n)\n\ntype MessageName struct {\n    msg.Package `ros:\"my_package\"`\n    Field1 bool\n    Field2 int32\n}\n```\n\nThe 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:\n\n```go\ntype MessageName struct {\n    msg.Package `ros:\"my_package\"`\n    msg.Name `ros:\"my_message_name\"`\n    Field1 bool\n    Field2 int32\n}\n```\n\nThe type of a field can be one of the following:\n\n* one of the primitive field types: `bool`, `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, `float64`, `string`, `time.Time`, `time.Duration`\n\n* another standard or custom message\n\nThe 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:\n\n```go\ntype MessageName struct {\n    msg.Package `ros:\"my_package\"`\n    Field bool  `rosname:\"FIELD\"`\n}\n```\n\nServices in this format:\n\n```\nuint32 input\n---\nuint32 output\n```\n\nAre equivalent to Go structures in this format:\n\n```go\ntype ServiceNameReq struct {\n    Input uint32\n}\n\ntype ServiceNameRes struct {\n\tOutput uint32\n}\n\ntype ServiceName struct {\n\tmsg.Package `ros:\"my_package\"`\n\tServiceNameReq\n\tServiceNameRes\n}\n```\n\nActions in this format:\n\n```\nuint32 goal\n---\nuint32 result\n---\nuint32 feedback\n```\n\nAre equivalent to Go structures in this format:\n\n```go\ntype ActionNameGoal struct {\n\tGoal uint32\n}\n\ntype ActionNameResult struct {\n\tResult uint32\n}\n\ntype ActionNameFeedback struct {\n\tFeedback uint32\n}\n\ntype ActionName struct {\n\tmsg.Package `ros:\"my_package\"`\n\tActionNameGoal\n\tActionNameResult\n\tActionNameFeedback\n}\n```\n\n### Import existing messages, services and actions\n\nYou can convert existing `.msg` files into their equivalent Go structures by using the `msg-import` tool:\n\n```\ngo install github.com/bluenviron/goroslib/v2/cmd/msg-import@latest\nmsg-import --rospackage=my_package mymessage.msg \u003e mymessage.go\n```\n\nYou can convert existing `.srv` files into their equivalent Go structures by using the `srv-import` tool:\n\n```\ngo install github.com/bluenviron/goroslib/v2/cmd/srv-import@latest\nsrv-import --rospackage=my_package myservice.srv \u003e myservice.go\n```\n\nYou can convert existing `.action` files into their equivalent Go structures by using the `action-import` tool:\n\n```\ngo install github.com/bluenviron/goroslib/v2/cmd/action-import@latest\naction-import --rospackage=my_package myaction.action \u003e myaction.go\n```\n\nTo convert a whole ROS package to Go, you can use the `package-import` tool:\n\n```\ngo install github.com/bluenviron/goroslib/v2/cmd/package-import@latest\npackage-import \u003cpath-to-ros-package\u003e\n```\n\n### Compile a node for another operating system\n\nTo 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:\n\n```\nGOOS=windows GOARCH=amd64 go build -o node.exe name-of-source-file.go\n```\n\n### Edit the library\n\nIf you want to hack the library and test the results, unit tests can be launched with:\n\n```\nmake test\n```\n\n## Specifications\n\n|name|area|\n|----|----|\n|[Technical overview](https://wiki.ros.org/ROS/Technical%20Overview)|general|\n|[Implementing client libraries](https://wiki.ros.org/Implementing%20Client%20Libraries)|general|\n|[Names](http://wiki.ros.org/Names)|general|\n|[Actionlib](http://wiki.ros.org/actionlib)|action lib|\n|[Actionlib detailed description](http://wiki.ros.org/actionlib/DetailedDescription)|action lib|\n|[Master API](https://wiki.ros.org/ROS/Master_API)|API|\n|[Parameter server API](https://wiki.ros.org/ROS/Parameter%20Server%20API)|API|\n|[Slave API](https://wiki.ros.org/ROS/Slave_API)|API|\n|[Connection header](https://wiki.ros.org/ROS/Connection%20Header)|protocol|\n|[TCPROS](https://wiki.ros.org/ROS/TCPROS)|protocol|\n|[UDPROS](https://wiki.ros.org/ROS/UDPROS)|protocol|\n|[Wireshark dissector](https://fossies.org/linux/wireshark/epan/dissectors/packet-prototcp.c)|protocol|\n|[Golang project layout](https://github.com/golang-standards/project-layout)|project layout|\n\n## Links\n\nOther Go libraries\n\n* [rosgo (v1)](https://github.com/akio/rosgo)\n* [rclgo (v2)](https://github.com/juaruipav/rclgo)\n\nOther non-Go libraries\n\n* [official library (v1) (C++)](https://github.com/ros/ros_comm/tree/noetic-devel/clients/roscpp/src/libros) ([documentation](https://docs.ros.org/noetic/api/roscpp/html/classros_1_1NodeHandle.html))\n* [official library (v1) (Python)](https://docs.ros.org/noetic/api/rosnode/html/)\n* [cros (v1) (C)](https://github.com/ros-industrial/cros)\n* [foxglove/ros1 (v1) (TypeScript)](https://github.com/foxglove/ros1)\n* [awesome ros2 (v2) (misc)](https://fkromer.github.io/awesome-ros2/)\n* [foxglove/ros2 (v2) (TypeScript)](https://github.com/foxglove/ros2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluenviron%2Fgoroslib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluenviron%2Fgoroslib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluenviron%2Fgoroslib/lists"}