Generate additional ROS2 TypeScript objects with details for serialization

[imcelroy]

Hi @minggangw,

First, thank you for all the work you've done on this project!

I am working on a problem where I am dealing with serializing and de-serializing binary ROS2 messages from a front-end app. I would like to directly use the TypeScript interfaces generated from npx generate-ros-messages. However, the number primitive type used to describe numbers in the current interfaces isn't explicit enough for serializing different types in numbers (int8, uint32, float64, etc).

Would it be possible to build additional TypeScript objects definitions that will facilitate serialization? For example:

Current TypeScript interface generated by npx generate-ros-messages:

namespace builtin_interfaces {
    namespace msg {
      export interface Duration {
        sec: number;
        nanosec: number;
      }
      export interface DurationConstructor {
        new(other?: Duration): Duration;
      }
      export interface Time {
        sec: number;
        nanosec: number;
      }
      export interface TimeConstructor {
        new(other?: Time): Time;
      }
    }
  }

Proposed additional interface in detail namespace:

namespace builtin_interfaces {
    namespace msg {
      export interface Duration {
        sec: number;
        nanosec: number;
      }
      export interface DurationConstructor {
        new(other?: Duration): Duration;
      }
      export interface Time {
        sec: number;
        nanosec: number;
      }
      export interface TimeConstructor {
        new(other?: Time): Time;
      }
    }
  }
    namespace detail {
      export interface Duration {
        sec: { value: number, type: "int32" };
        nanosec: { value: number, type: "uint32" };
      }
      export interface DurationConstructor {
        new(other?: Duration): Duration;
      }
      export interface Time {
        sec: { value: number, type: "int32" };
        nanosec: { value: number, type: "uint32" };
      }
      export interface TimeConstructor {
        new(other?: Time): Time;
      }
    }
  }

Maybe this information is already available somewhere? Thanks for your help!

I would be up for volunteering to work on this feature if you think it is something that could be interesting for rclnodejs.

[minggangw]

Hi @imcelroy thanks for your feedback, the current interfaces.d.ts in the npm package is generated from .mgs, like Duration.

# Seconds component, range is valid over any possible int32 value.
int32 sec

# Nanoseconds component in the range of [0, 1e9).
uint32 nanosec

Would you provide more information about the case you gave, for example if creating a subscription:

let subscription = node.createSubscription('builtin_interfaces/msg/Duration', 'time', () => {});

I want to understand when you need an explicit type like the one defined in namespace detail and how do you leverage the type? thanks!

[imcelroy]

Hi @minggangw, thank you for the fast reply! Here is our use case:

We are communicating with ROS via foxglove-bridge, which uses binary messages. The reason why I'm reaching out to you is because we would like to use rclnodejs as our "source of truth" for creating the message definitions (standard and custom messages), instead of using strings as shown here: foxglove/rosmsg. These definitions are then passed to the serializers/deserializers shown here: foxglove/rosmsg2-serialization.

rclnodejs already parses the .msg files as you said, and it already contains all of the type details (for numbers in particular) during the parsing. The idea is to add additional Typescript interfaces that can be used to create the objects needed by the foxglove-bridge MessageReader/Writer.

Here is a simplified workflow describing what I am trying to accomplish:

# proposed addition to interfaces.d.ts
namespace builtin_interfaces {
    namespace msg {
        namespace detail {
          export interface Duration {
            sec: { value: number, type: "int32" };
            nanosec: { value: number, type: "uint32" };
          }
      }
    }
}

This proposed definition would be used to create an object in the following format, which is needed for the foxglove-bridge MessageReader/Writer:

import { 
    builtin_interfaces
} from 'rclnodejs';

import { MessageReader } from '@foxglove/rosmsg2-serialization';

const default_Duration: builtin_interfaces.msg.detail.Duration = { 
    sec: { value: 0, type: "int32" }, 
    nanosec: {value: 0, type: "uint32" }
};
# getMessageDefinitions (custom function I built and can provide if needed) 
const durationDefinition = getMessageDefinitions(default_Duration, "builtin_interfaces/msg/Duration");

console.log(durationDefinition);
# prints the following
# {
#    "name": "builtin_interfaces/msg/Time",
#    "definitions": [
#      {
#        "name": "sec",
#        "type": "int32",
#        "isComplex": false,
#        "isArray": false
#      },
#      {
#        "name": "nanosec",
#        "type": "uint32",
#        "isComplex": false,
#        "isArray": false
#      }
#    ]
#  }

const durationReader = MessageReader(durationDefinition)

I'd be happy to provide more details if you would like, thank you again for your time.

[minggangw]

I see, thanks for your explanation. It makes sense if user want to know the exact types. Before moving forward, what I can think out is

1. How can we avoid user from writing the code below which may cause runtime error.

subscription = node.createSubscription(
  'builtin_interfaces/msg/detail/Duration',
  'druration',
  { isRaw: false },
  (message: builtin_interfaces.msg.detail.Duration) => {
    console.log(message.value.sec);
  }
);

Generally, we can depend on the type of the callback like:

rclnodejs/types/subscription.d.ts

Lines 14 to 32 in baba669

	type SubscriptionCallback<T extends TypeClass<MessageTypeClassName>> =
	// * @param message - The published message
	(message: MessageType<T>) => void;
	/**
	* A callback for receiving published raw messages.
	*
	* @param message - The published message.
	*
	* @remarks
	* See {@link Node#createSubscription | Node.createSubscription}
	* See {@link SubscriptionContentFilter}
	* See {@link Node#createPublisher | Node.createPublisher}
	* See {@link Publisher}
	* See {@link Subscription}
	*/
	type SubscriptionWithRawMessageCallback =
	// * @param message - The published raw message
	(message: Buffer) => void;

Is there any other solution not causing confusion?

2. Are we going to provide the detailed types for all messages defined in current ROS2 (not including customized ones), I deem we should do that.

If we can solve them, we are good to go 😄 or you could open a PR to demonstrate what it looks like, thanks!

[imcelroy]

Good points @minggangw. I hadn't considered the fact that the detailed messages could be used for subscribers/publishers.

What if we change the namespace name from detail to descriptor to be clearer, and we change the interface like this, where the value of the field is a string describing the field type?

namespace builtin_interfaces {
  namespace msg {
    namespace descriptor {
      export interface Duration {
        sec: "int32";
        nanosec: "uint32";
      }
    }
    export interface Duration {
      sec: number;
      nanosec: number;
    }
  }
}

This way it is very clear that the new descriptor interface is describing the message, and the same message structure exists. In other words, both of these should technically work:

subscription = node.createSubscription(
  'builtin_interfaces/msg/Duration',
  'duration',
  { isRaw: false },
  (message: builtin_interfaces.msg.Duration) => {
    console.log("message.value.sec type: ", typeof message.value.sec); # prints number
  }
);

and:

subscription = node.createSubscription(
  'builtin_interfaces/msg/descriptor/Duration',
  'duration',
  { isRaw: false },
  (message: builtin_interfaces.msg.descriptor.Duration) => {
    console.log("message.value.sec type: ", typeof message.value.sec); # prints string
  }
);

Regarding your second point, I definitely agree that whatever our solution it, it should be applied to all messages, not just customized messages!

I can start a PR if this sounds good to you. Thanks for your help!

[minggangw]

@imcelroy Your proposal of renaming namespace to descriptor looks good to me, please go ahead to start your PR, thanks!

[imcelroy]

Resolved with #1095