node-mavlink-gen

A powerful source code generator for node-mavlink-compatible classes. Uses the same code that powers the mavlink-mappings package used by node-mavlink.

Usage

It's really easy to get going!

$ npx node-mavlink-gen@latest minimal.xml

(You can get the minimal.xml file from here)

After you run the command the generator will read all the files you specified in the command line and generate source code for each module. If you have specified multiple files those will instead be written to their respective files.

Getting a colored output

There is a way to easily get the code syntax highlighted using the source-highlight utility:

$ npx node-mavlink-gen minimal.xml | source-highlight -s javascript -f esc256 | less -r

Generating custom definitions

Sometimes the vast number of messages just isn't enough and a new message could make all the difference.

You may consider writing the a class definition by hand, which is definitely possible but it may be a tedious and error-prone process. To ease the pain the entire generator is exposed for anyone to use:

Generating based on XML source

One thing that will allow you to basically generate all definitions in one go is to base them on a mavlink xml definition file. For a list of supported features look at the original XML definitions. At the moment minimal, common, development, ardupilotmega, asluav, icarus, storm32, ualberta and uavionix definitions are recognized by the generator.

async function generateAll(input: string, output: Writer, moduleName: string = '')

Generating based on data

This is a much more tedious process but it allows you to use something completely different to read the definitions from. There are a few interfaces that you'll have to get familiar with (like EnumDef, MessageDef and CommandTypeDef) but after you'll get them the generator should produce valid definitions.

This is how the generateAll() function does it:

const { enumDefs, messageDefs, commandTypeDefs } = await new XmlDataSource().parse(input)

const enums = processEnums(output, enumDefs)
const messages = processMessages(output, messageDefs)
const commands = processCommands(output, moduleName, commandTypeDefs)
processRegistries(output, messages, commands)

return { enums, messages, commands }

Debugging issues

Disclaimer:

The generator is basically available as-is. There is, and never will be, any support for anything else that doesn't work at the moment. If you want to have a problem fixed that impacts you - create a PR, I promise I'll look at it. If you have a feature request - create a PR that implements that feature.

With that out of the way let's see what can we do to understand the problems we might encounter.

Going single

If only part of the generation fails the entire generated content is lost. But there is hope! You can process each enum, message and command separately:

Generating a single enum

function generateEnum(output: Writer, enum: {
  name: string
  description: string[]
  values: {
    name: string
    value: string
    description: string[]
    hasLocation: boolean
    isDestination: boolean
    params: {
      name: string
      label: string
      description: string
      index: string
      units: string
      minValue: string
      maxValue: string
      increment: string
    }[]
  }[]
  source: {
    name: string
  }
})

Generating a single message

function generateMessage(output: Writer, message: {
  id: string
  name: string
  description: string[]
  magic?: number
  payloadLength?: number
  source: {
    name: string
  }
  deprecated?: {
    description: string
    since: string
    replacedBy: string
  }
  fields: {
    name: string
    description: string[]
    fieldSize: number
    extension: boolean
    arrayLength: number
    fieldType: string
    size: number
    units: string
    type: string
    source: {
      name: string
    }
  }[]
})

Generating a single command

function generateCommand(output: Writer, command: {
  description: string[],
  hasLocation: boolean,
  isDestination: boolean,
  field: string,
  name: string,
  params: {
    name: string,
    index: string,
    description: string[]
    label: string
    units: string
    minValue: string
    maxValue: string
    increment: string
  }[]
  source: {
    commonPrefix?: string
  }
})

Generating other elements separately

Pretty much every single part of the code can be generated in separation to everything else. Use that to understand better the inputs and the generated output. Functions like generateEnumValueParams(...) or generateMessageDefinitionFields() are there for you to use in those cases where you just don't get what's going on.

Generating magic number (aka crc_extra) value

Writing a definition of a message manually is an intense task at best. The one thing that is the least straightforward is the generation of a proper crc_extra (referred by node-mavlink as magic value) value:

function calculateCrcExtra(messageSourceName: string, fields: {
  extension: boolean
  itemType: string
  fieldSize: number
  arrayLength?: number
  source: { type: string, name: string }
}[])

Generating registry for magic numbers

A registry of magic numbers (aka crc_extra) can also be generated:

  fs.writeFileSync('magic-numbers.ts', generateMagicNumbers(magicNumbers))