Guide: Create message converter
This guide takes you through building an extension for a message converter. You'll learn how to setup your extension project and build a simple converter for a custom GPS message to foxglove.LocationFix
for visualizing in the Map panel.
Setting up
In a Terminal window, cd
into the directory where your source code will live and run the following command:
$ npm init foxglove-extension@latest myExtensionName
This uses create-foxglove-extension
to create a myExtensionName
directory containing source code for an example message converter.
Registering a converter
The index.ts
file in your project's src
folder is the entry point for your extension source code. It must export an activate
function that accepts a single extensionContext
argument of type ExtensionContext
.
To register a message converter, we call registerMessageConverter
on the extensionContext
argument with three arguments: the source schema type, the destination schema type, and the actual converter function.
export function activate(extensionContext: ExtensionContext) {
extensionContext.registerMessageConverter({
fromSchemaName: "...",
toSchemaName: "...",
converter: (inputMessage) => {
// ...
},
});
}
Writing the converter
Let's assume that our data contains GPS messages of type sensors.MyGps
, which contain a lat
and lon
field.
To visualize GPS coordinates, the Map panel requires messages in the foxglove.LocationFix
format. In short, our converter needs to turn MyGps
messages into messages that adhere to the foxglove.LocationFix
schema.
First, specify the from schema (sensors.MyGps
) and to schema (foxglove.LocationFix
), to inform Studio that our registered converter will turn sensors.MyGps
messages into foxglove.LocationFix
messages.
Then, write the converter function. In our example, we'll re-map the lat
and lon
fields to the latitude
and longitude
fields that the foxglove.LocationFix
schema expects:
type MyGps = {
lat: number;
lon: number;
};
export function activate(extensionContext: ExtensionContext) {
extensionContext.registerMessageConverter({
fromSchemaName: "sensors.MyGps",
toSchemaName: "foxglove.LocationFix",
converter: (myGps: MyGps) => {
return {
latitude: myGps.lat,
longitude: myGps.lon,
};
},
});
}
Testing
Once we've packaged and installed our extension, load any data source containing sensors.MyGps
messages in Studio and visualize them with the Map panel.