viam-ros-sensor-bridge
This is a module that is not intended to be published to the public Viam Registry. Instead it is intended to be forked and implemented in private for each user. This is because custome ROS types have to be mapped and this could expose proprietary information.
The Module
This module can be used in 2 ways, as a Local Module or by using the Viam Registry. If you opt to use the Viam Registry, do not use the Public Registry (set the visibility to private
) or the Registry will become cluttered with many versions of this module which are likely useless to anybody but you.
The Components
Publisher
The publisher is used to move data from Viam to ROS. Only 1 Publisher component is required to support multiple sensors.
Sample Configuration:
{
"primary_uri": "localhost:11311",
"sensors": [
{
"topic": "/sensors/throttling_states",
"message_type": "throttling",
"sensor_name": "throttling",
"sample_rate": 1
},
{
"topic": "/states/uptime",
"message_type": "std_msgs/Int32",
"sensor_name": "uptime",
"sample_rate": 1
}
]
}
The throttling
sensor must return data in the following format:
{
Undervoltage: false,
ArmFrequentlyCapped: false,
Throttled: false,
SoftTemperatureLimitActive: false,
UndervoltageOccurred: false,
ArmFrequentlyCappedOccurred: false,
ThrottlingOccurred: false,
SoftTemperatureLimitOccurred: false
}
The uptime
sensor must return data in the following format:
{
Data: <int>
}
These match exactly the struct definitions in the code. Any other fields will be ignored. If the type for a field is incorrect (eg: "false"
instead of false
), it will likely result in a serialization error and no data transmitted to ROS.
Subscriber
The subscriber is used to move data from ROS to Viam. Only 1 subscriber is created per-component. This is because the data returned by readings
would get really messy for complex message types.
Sample Configuration:
{
"primary_uri": "localhost:11311",
"sensor": {
"topic": "/states/uptime",
"message_type": "std_msgs/Int32"
}
}
This will create a sensor where the data returned by readings
is
{ Data: <int> }
How to add your own messages
- Use the tools from goroslib to convert the IDL files to go structs
- Add the struct to custom_messages.go (or your own file in that package)
- Update the custom_registry to add the new type to the registry so that your new types are properly handled. Please see ThrottlingStates for an example on doing this.
- Add any appropriate tests
DO NOT CHANGE standard_messages.go
or message_handler.go
How to build
- Compile the module
go build -o viam-ros-sensor-bridge module.go
Be sure to use GOOS
and GOARCH
environment variables when necessary. For example, to build on x86_64 to run on a Raspberry Pi.
GOOS=linux GOARCH=arm64 go build -o viam-ros-sensor-bridge module.go
- (Optional) Move the binary to your robot and test
- (Optional) Publish to your private Viam Repository
DO NOT PUBLISH TO THE PUBLIC REPOSITORY
FAQ
A sensor needs to return data in the exact format of the message to be sent to ROS. You can find the format of ROS message data by looking at the definitions in goroslib
.
For example, if you want to send an Int32 from your sensor to ROS, the readings() method needs to return the integer value where the key is Data
.
{ Data: 42 }
For a string, the format is:
{ Data: "Hello World!" }
Q: I don't want to make my message types public, how do I keep in sync with your repository?
It is not uncommon that you may want to protect your messages by not publishing them publicly. The easiest way to do this is to create a private repository on GitHub and manually syncing this repository with yours.
- Create an empty private repository under your organization
- Clone this repository
- Change the remote name
git remote rename origin upstream
- Add your new repository as the origin
git remote add origin <new_git_uri>
- Push the code to your repository
git push origin
Now to sync changes from upstream:
git fetch upstream
git push origin
Be careful when making changes to limit them just to just the following files:
I will try to restrict changes to these files so they won't conflict with your local changes.