ROS 2 rules#

use pamoja_ros2::name::{dds_topic, is_fully_qualified, is_valid_name, EntityKind};
use pamoja_ros2::typehash::dds_type_name;

// A name is slash-separated tokens of letters, digits, and underscores. A token may not
// start with a digit, and a name may not end in a slash, hold an empty token, or double
// an underscore.
let camera = "/robot1/camera_left/image_raw";
if is_valid_name(camera) {
    println!("valid     {camera}");
}
for (name, why) in [
    ("/2foo", "a token starts with a digit"),
    ("/cmd_vel/", "it ends in a slash"),
    ("/robot1//odom", "it has an empty token"),
    ("/robot1/cmd__vel", "it doubles an underscore"),
] {
    if !is_valid_name(name) {
        println!("invalid   {name}, since {why}");
    }
}

// A name with no leading slash is relative, and one that starts with a tilde is private.
// Both are valid, and both resolve against the node before they reach the wire, so
// neither is fully qualified.
for (label, name, against) in [
    ("relative", "cmd_vel", "the node's namespace"),
    ("private", "~/setpoint", "the node's own name"),
] {
    if is_valid_name(name) && !is_fully_qualified(name) {
        println!("{label:<10}{name} is valid, and resolves against {against} first");
    }
}

// Only a fully qualified name reaches the wire. DDS puts a prefix before it that says
// what kind of endpoint it is, and a service travels on two topics, each ending in the
// suffix the middleware appends.
let published = dds_topic("/robot1/cmd_vel", EntityKind::Topic).expect("a qualified name");
let asked =
    dds_topic("/robot1/add_two_ints", EntityKind::ServiceRequest).expect("a qualified name");
let answered =
    dds_topic("/robot1/add_two_ints", EntityKind::ServiceResponse).expect("a qualified name");
println!("topic     /robot1/cmd_vel travels on {published}");
println!("request   /robot1/add_two_ints asks on {asked}");
println!("reply     and answers on {answered}");

// A message type maps to a DDS type name the same way, so both ends agree on what is
// carried before a byte is exchanged. A name that is not package/namespace/Type maps to
// nothing rather than to something plausible.
for ros_type in [
    "std_msgs/msg/String",
    "example_interfaces/srv/AddTwoInts",
    "std_msgs/String",
] {
    match dds_type_name(ros_type) {
        Some(carried) => println!("type      {ros_type} is named {carried}"),
        None => println!(
            "malformed {ros_type} is not package/namespace/Type, so it has no DDS type name"
        ),
    }
}

use pamoja_ros2::key::entity_key;
use pamoja_ros2::name::percent_mangle;
use pamoja_ros2::typehash::TypeHash;

// A type hash pins the message definition itself, so two builds of a message that share
// a name but not a layout never talk. This is the hash rosidl publishes for
// std_msgs/msg/String: RIHS01, then a SHA-256 in hex.
const STRING_HASH: &str =
    "RIHS01_df668c740482bbd48fb39d76a70dfd4bd59db1288021743503259e948f6b1a18";
let hash = TypeHash::parse(STRING_HASH).expect("the published hash");
println!(
    "hash      std_msgs/msg/String carries RIHS01 with a {}-byte SHA-256",
    hash.digest().len()
);

// rmw_zenoh puts a topic on the key <domain>/<name>/<type>/<hash>, so a peer that builds
// the same key talks to ROS 2 nodes with no DDS in the path.
let key = entity_key(0, "/chatter", "std_msgs/msg/String", &hash).expect("a usable key");
println!("key       {key}");
if entity_key(0, "chatter", "std_msgs/msg/String", &hash).is_none() {
    println!("no key    a relative name has no key until the node resolves it");
}

// A hash one digit short is not a hash, and is refused rather than matched loosely.
if TypeHash::parse(&STRING_HASH[..STRING_HASH.len() - 1]).is_none() {
    println!("refused   a hash one hex digit short is not RIHS01");
}

// A liveliness token says who is on the graph, and in it rmw_zenoh writes each slash of
// a name as a percent sign.
println!(
    "token     /robot1/chatter is written {} in a liveliness token",
    percent_mangle("/robot1/chatter")
);

use pamoja_ros2::msg::{CdrReader, CdrWriter, Twist, Vector3};

// A command velocity: half a meter a second forward, turning at 0.2 radians a second.
// CDR opens with a four-byte header naming the byte order, then the six doubles.
let cmd = Twist {
    linear: Vector3::new(0.5, 0.0, 0.0),
    angular: Vector3::new(0.0, 0.0, 0.2),
};
let bytes = cmd.to_cdr();
println!(
    "twist     {} bytes: a 4-byte header, then six 8-byte doubles",
    bytes.len()
);
let back = Twist::from_cdr(&bytes).expect("a whole twist");
println!(
    "decoded   forward {} m/s, turning {} rad/s, the command that was sent",
    back.linear.x, back.angular.z
);

// Each value is aligned to its own size, counted from after the header, so an integer
// followed by a double takes four bytes of padding before the double.
let mut writer = CdrWriter::new();
writer.write_i32(7);
writer.write_f64(2.5);
let mixed = writer.into_bytes();
let mut reader = CdrReader::new(&mixed).expect("a CDR header");
let count = reader.read_i32().expect("an integer");
let level = reader.read_f64().expect("a double");
println!(
    "aligned   an i32 then an f64 take {} bytes, not 16, and read back as {count} and {level}",
    mixed.len()
);

// A message cut short decodes as nothing rather than as a plausible command.
if Twist::from_cdr(&bytes[..bytes.len() - 8]).is_none() {
    println!("short     a twist missing its last double decodes as nothing");
}

import { EntityKind, name } from '@pamoja/ros2'

// A name is slash-separated tokens of letters, digits, and underscores. A token may not start
// with a digit, and a name may not end in a slash, hold an empty token, or double an
// underscore.
const camera = '/robot1/camera_left/image_raw'
if (name.isValid(camera)) {
  console.log(`valid     ${camera}`)
}
for (const [candidate, why] of [
  ['/2foo', 'a token starts with a digit'],
  ['/cmd_vel/', 'it ends in a slash'],
  ['/robot1//odom', 'it has an empty token'],
  ['/robot1/cmd__vel', 'it doubles an underscore'],
]) {
  if (!name.isValid(candidate)) {
    console.log(`invalid   ${candidate}, since ${why}`)
  }
}

// A name with no leading slash is relative, and one that starts with a tilde is private. Both
// are valid, and both resolve against the node before they reach the wire, so neither is
// fully qualified.
for (const [label, candidate, against] of [
  ['relative', 'cmd_vel', "the node's namespace"],
  ['private', '~/setpoint', "the node's own name"],
]) {
  if (name.isValid(candidate) && !name.isFullyQualified(candidate)) {
    console.log(`${label.padEnd(10)}${candidate} is valid, and resolves against ${against} first`)
  }
}

// Only a fully qualified name reaches the wire. DDS puts a prefix before it that says what
// kind of endpoint it is, and a service travels on two topics, each ending in the suffix the
// middleware appends.
const published = name.ddsTopic('/robot1/cmd_vel', EntityKind.Topic)
const asked = name.ddsTopic('/robot1/add_two_ints', EntityKind.ServiceRequest)
const answered = name.ddsTopic('/robot1/add_two_ints', EntityKind.ServiceResponse)
console.log(`topic     /robot1/cmd_vel travels on ${published}`)
console.log(`request   /robot1/add_two_ints asks on ${asked}`)
console.log(`reply     and answers on ${answered}`)

// A message type maps to a DDS type name the same way, so both ends agree on what is carried
// before a byte is exchanged. A name that is not package/namespace/Type maps to nothing
// rather than to something plausible.
for (const rosType of ['std_msgs/msg/String', 'example_interfaces/srv/AddTwoInts', 'std_msgs/String']) {
  const carried = name.ddsTypeName(rosType)
  if (carried !== null) {
    console.log(`type      ${rosType} is named ${carried}`)
  } else {
    console.log(`malformed ${rosType} is not package/namespace/Type, so it has no DDS type name`)
  }
}

import { typeHash } from '@pamoja/ros2'

// A type hash pins the message definition itself, so two builds of a message that share a
// name but not a layout never talk. This is the hash rosidl publishes for
// std_msgs/msg/String: RIHS01, then a SHA-256 in hex.
const STRING_HASH = 'RIHS01_df668c740482bbd48fb39d76a70dfd4bd59db1288021743503259e948f6b1a18'
const digest = typeHash.digest(STRING_HASH)
console.log(`hash      std_msgs/msg/String carries RIHS01 with a ${digest?.length}-byte SHA-256`)

// rmw_zenoh puts a topic on the key <domain>/<name>/<type>/<hash>, so a peer that builds the
// same key talks to ROS 2 nodes with no DDS in the path.
const key = typeHash.entityKey(0, '/chatter', 'std_msgs/msg/String', STRING_HASH)
console.log(`key       ${key}`)
if (typeHash.entityKey(0, 'chatter', 'std_msgs/msg/String', STRING_HASH) === null) {
  console.log('no key    a relative name has no key until the node resolves it')
}

// A hash one digit short is not a hash, and is refused rather than matched loosely.
if (typeHash.digest(STRING_HASH.slice(0, -1)) === null) {
  console.log('refused   a hash one hex digit short is not RIHS01')
}

// A liveliness token says who is on the graph, and in it rmw_zenoh writes each slash of a
// name as a percent sign.
console.log(
  `token     /robot1/chatter is written ${name.percentMangle('/robot1/chatter')} in a liveliness token`,
)

import { cdr } from '@pamoja/ros2'

// A command velocity: half a meter a second forward, turning at 0.2 radians a second. CDR
// opens with a four-byte header naming the byte order, then the six doubles.
const command = { linear: { x: 0.5, y: 0, z: 0 }, angular: { x: 0, y: 0, z: 0.2 } }
const bytes = cdr.twistToBytes(command)
console.log(`twist     ${bytes.length} bytes: a 4-byte header, then six 8-byte doubles`)
const back = cdr.twistFromBytes(bytes)!
console.log(
  `decoded   forward ${back.linear.x} m/s, turning ${back.angular.z} rad/s, the command that was sent`,
)

// Each value is aligned to its own size, counted from after the header, so an integer
// followed by a double takes four bytes of padding before the double.
const writer = cdr.writer()
writer.writeI32(7)
writer.writeF64(2.5)
const mixed = writer.bytes
const reader = cdr.reader(mixed)
const count = reader.readI32()
const level = reader.readF64()
console.log(
  `aligned   an i32 then an f64 take ${mixed.length} bytes, not 16, and read back as ${count} and ${level}`,
)

// A message cut short decodes as nothing rather than as a plausible command.
if (cdr.twistFromBytes(bytes.subarray(0, bytes.length - 8)) === null) {
  console.log('short     a twist missing its last double decodes as nothing')
}

from pamoja.ros2 import EntityKind, dds_topic, dds_type_name, is_fully_qualified, is_valid_name

# A name is slash-separated tokens of letters, digits, and underscores. A token may not start
# with a digit, and a name may not end in a slash, hold an empty token, or double an
# underscore.
camera = "/robot1/camera_left/image_raw"
if is_valid_name(camera):
    print(f"valid     {camera}")
for name, why in [
    ("/2foo", "a token starts with a digit"),
    ("/cmd_vel/", "it ends in a slash"),
    ("/robot1//odom", "it has an empty token"),
    ("/robot1/cmd__vel", "it doubles an underscore"),
]:
    if not is_valid_name(name):
        print(f"invalid   {name}, since {why}")

# A name with no leading slash is relative, and one that starts with a tilde is private. Both
# are valid, and both resolve against the node before they reach the wire, so neither is
# fully qualified.
for label, name, against in [
    ("relative", "cmd_vel", "the node's namespace"),
    ("private", "~/setpoint", "the node's own name"),
]:
    if is_valid_name(name) and not is_fully_qualified(name):
        print(f"{label:<10}{name} is valid, and resolves against {against} first")

# Only a fully qualified name reaches the wire. DDS puts a prefix before it that says what
# kind of endpoint it is, and a service travels on two topics, each ending in the suffix the
# middleware appends.
published = dds_topic("/robot1/cmd_vel", EntityKind.TOPIC)
asked = dds_topic("/robot1/add_two_ints", EntityKind.SERVICE_REQUEST)
answered = dds_topic("/robot1/add_two_ints", EntityKind.SERVICE_RESPONSE)
print(f"topic     /robot1/cmd_vel travels on {published}")
print(f"request   /robot1/add_two_ints asks on {asked}")
print(f"reply     and answers on {answered}")

# A message type maps to a DDS type name the same way, so both ends agree on what is carried
# before a byte is exchanged. A name that is not package/namespace/Type maps to nothing rather
# than to something plausible.
for ros_type in ["std_msgs/msg/String", "example_interfaces/srv/AddTwoInts", "std_msgs/String"]:
    carried = dds_type_name(ros_type)
    if carried is not None:
        print(f"type      {ros_type} is named {carried}")
    else:
        print(f"malformed {ros_type} is not package/namespace/Type, so it has no DDS type name")

from pamoja.ros2 import entity_key, percent_mangle, type_hash_digest

# A type hash pins the message definition itself, so two builds of a message that share a
# name but not a layout never talk. This is the hash rosidl publishes for std_msgs/msg/String:
# RIHS01, then a SHA-256 in hex.
STRING_HASH = "RIHS01_df668c740482bbd48fb39d76a70dfd4bd59db1288021743503259e948f6b1a18"
digest = type_hash_digest(STRING_HASH)
print(f"hash      std_msgs/msg/String carries RIHS01 with a {len(digest)}-byte SHA-256")

# rmw_zenoh puts a topic on the key <domain>/<name>/<type>/<hash>, so a peer that builds the
# same key talks to ROS 2 nodes with no DDS in the path.
key = entity_key(0, "/chatter", "std_msgs/msg/String", STRING_HASH)
print(f"key       {key}")
if entity_key(0, "chatter", "std_msgs/msg/String", STRING_HASH) is None:
    print("no key    a relative name has no key until the node resolves it")

# A hash one digit short is not a hash, and is refused rather than matched loosely.
if type_hash_digest(STRING_HASH[:-1]) is None:
    print("refused   a hash one hex digit short is not RIHS01")

# A liveliness token says who is on the graph, and in it rmw_zenoh writes each slash of a name
# as a percent sign.
print(
    f"token     /robot1/chatter is written {percent_mangle('/robot1/chatter')} "
    "in a liveliness token"
)

from pamoja.ros2 import CdrReader, CdrWriter, twist_from_cdr, twist_to_cdr

# A command velocity: half a meter a second forward, turning at 0.2 radians a second. CDR
# opens with a four-byte header naming the byte order, then the six doubles.
linear, angular = (0.5, 0.0, 0.0), (0.0, 0.0, 0.2)
data = twist_to_cdr(linear, angular)
print(f"twist     {len(data)} bytes: a 4-byte header, then six 8-byte doubles")
back_linear, back_angular = twist_from_cdr(data)
print(
    f"decoded   forward {back_linear[0]:g} m/s, turning {back_angular[2]:g} rad/s, "
    "the command that was sent"
)

# Each value is aligned to its own size, counted from after the header, so an integer
# followed by a double takes four bytes of padding before the double.
writer = CdrWriter()
writer.write_i32(7)
writer.write_f64(2.5)
mixed = writer.bytes
reader = CdrReader(mixed)
count = reader.read_i32()
level = reader.read_f64()
print(
    f"aligned   an i32 then an f64 take {len(mixed)} bytes, not 16, "
    f"and read back as {count} and {level:g}"
)

# A message cut short decodes as nothing rather than as a plausible command.
if twist_from_cdr(data[:-8]) is None:
    print("short     a twist missing its last double decodes as nothing")

// A name is slash-separated tokens of letters, digits, and underscores. A token may
// not start with a digit, and a name may not end in a slash, hold an empty token, or
// double an underscore.
const string camera = "/robot1/camera_left/image_raw";
if (Ros2.IsValidName(camera))
{
    Console.WriteLine($"valid     {camera}");
}

foreach ((string name, string why) in new[]
{
    ("/2foo", "a token starts with a digit"),
    ("/cmd_vel/", "it ends in a slash"),
    ("/robot1//odom", "it has an empty token"),
    ("/robot1/cmd__vel", "it doubles an underscore"),
})
{
    if (!Ros2.IsValidName(name))
    {
        Console.WriteLine($"invalid   {name}, since {why}");
    }
}

// A name with no leading slash is relative, and one that starts with a tilde is
// private. Both are valid, and both resolve against the node before they reach the
// wire, so neither is fully qualified.
foreach ((string label, string name, string against) in new[]
{
    ("relative", "cmd_vel", "the node's namespace"),
    ("private", "~/setpoint", "the node's own name"),
})
{
    if (Ros2.IsValidName(name) && !Ros2.IsFullyQualified(name))
    {
        Console.WriteLine($"{label,-10}{name} is valid, and resolves against {against} first");
    }
}

// Only a fully qualified name reaches the wire. DDS puts a prefix before it that says
// what kind of endpoint it is, and a service travels on two topics, each ending in the
// suffix the middleware appends.
string? published = Ros2.DdsTopic("/robot1/cmd_vel", EntityKind.Topic);
string? asked = Ros2.DdsTopic("/robot1/add_two_ints", EntityKind.ServiceRequest);
string? answered = Ros2.DdsTopic("/robot1/add_two_ints", EntityKind.ServiceResponse);
Console.WriteLine($"topic     /robot1/cmd_vel travels on {published}");
Console.WriteLine($"request   /robot1/add_two_ints asks on {asked}");
Console.WriteLine($"reply     and answers on {answered}");

// A message type maps to a DDS type name the same way, so both ends agree on what is
// carried before a byte is exchanged. A name that is not package/namespace/Type maps
// to nothing rather than to something plausible.
foreach (string rosType in new[]
{
    "std_msgs/msg/String",
    "example_interfaces/srv/AddTwoInts",
    "std_msgs/String",
})
{
    Console.WriteLine(Ros2.DdsTypeName(rosType) is { } carried
        ? $"type      {rosType} is named {carried}"
        : $"malformed {rosType} is not package/namespace/Type, so it has no DDS type name");
}

// A type hash pins the message definition itself, so two builds of a message that
// share a name but not a layout never talk. This is the hash rosidl publishes for
// std_msgs/msg/String: RIHS01, then a SHA-256 in hex.
const string stringHash =
    "RIHS01_df668c740482bbd48fb39d76a70dfd4bd59db1288021743503259e948f6b1a18";
byte[]? digest = Ros2.TypeHashDigest(stringHash);
Console.WriteLine($"hash      std_msgs/msg/String carries RIHS01 with a {digest?.Length}-byte SHA-256");

// rmw_zenoh puts a topic on the key <domain>/<name>/<type>/<hash>, so a peer that
// builds the same key talks to ROS 2 nodes with no DDS in the path.
string? key = Ros2.EntityKey(0, "/chatter", "std_msgs/msg/String", stringHash);
Console.WriteLine($"key       {key}");
if (Ros2.EntityKey(0, "chatter", "std_msgs/msg/String", stringHash) is null)
{
    Console.WriteLine("no key    a relative name has no key until the node resolves it");
}

// A hash one digit short is not a hash, and is refused rather than matched loosely.
if (Ros2.TypeHashDigest(stringHash[..^1]) is null)
{
    Console.WriteLine("refused   a hash one hex digit short is not RIHS01");
}

// A liveliness token says who is on the graph, and in it rmw_zenoh writes each slash
// of a name as a percent sign.
Console.WriteLine(
    $"token     /robot1/chatter is written {Ros2.PercentMangle("/robot1/chatter")} in a liveliness token");

// A command velocity: half a meter a second forward, turning at 0.2 radians a second.
// CDR opens with a four-byte header naming the byte order, then the six doubles.
var command = new Ros2Twist(new Vector3(0.5, 0, 0), new Vector3(0, 0, 0.2));
byte[] bytes = Ros2.TwistToCdr(command);
Console.WriteLine($"twist     {bytes.Length} bytes: a 4-byte header, then six 8-byte doubles");
Ros2Twist back = Ros2.TwistFromCdr(bytes) ?? throw new InvalidOperationException("a whole twist");
Console.WriteLine(Invariant(
    $"decoded   forward {back.Linear.X} m/s, turning {back.Angular.Z} rad/s, the command that was sent"));

// Each value is aligned to its own size, counted from after the header, so an integer
// followed by a double takes four bytes of padding before the double.
using var writer = new CdrWriter();
writer.WriteInt32(7);
writer.WriteDouble(2.5);
byte[] mixed = writer.ToBytes();
using var reader = new CdrReader(mixed);
int? count = reader.ReadInt32();
double? level = reader.ReadDouble();
Console.WriteLine(Invariant(
    $"aligned   an i32 then an f64 take {mixed.Length} bytes, not 16, and read back as {count} and {level}"));

// A message cut short decodes as nothing rather than as a plausible command.
if (Ros2.TwistFromCdr(bytes.AsSpan(0, bytes.Length - 8)) is null)
{
    Console.WriteLine("short     a twist missing its last double decodes as nothing");
}