Add a ROS 2 message type

Paths. scripts/… and references/… below are relative to the directory holding this SKILL.md. Your working directory is the user's project, not that directory, so prefix them with its absolute path or the command is not found.

CARLA serialises hand-written C++ PODs straight into CDR buffers with Fast-CDR. There is no IDL compiler in the build, so a new type is a five-file manual change. Skipping any one of them fails in a different way — silently on the wire, loudly at build, or only on a peer's Jazzy console.

Upstream reference: Docs/ros2/adding_message_types.md in the checkout. This skill adds the preflight, the wrapped hash computation, and the verify loop.

On CARLA 0.10.0 (the UE5 line: 5.5 and 5.8)

The hand-written-POD approach, the Fast-CDR serialize/deserialize pair, the RIHS01 type hash and the registration step are the same on 0.10.0 — there is still no IDL codegen.

What differs is the neighbourhood: types live beside a larger set on 0.10.0 (Autoware messages among them), and QoS moved from PublisherQos.h to QosProfile.h. If your new type is for a publisher, read [[add-ros-publisher]] first for the BasicPublisher refactor — a type added for a CarlaPublisher-shaped class will not compile there.

Instructions

Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Get the .msg definition (standard type, or write a carla_msgs one)
- [ ] Step 3: POD struct in types/msg/<Type>.h
- [ ] Step 4: serialize_cdr/deserialize_cdr pair in types/CdrSerialization.h
- [ ] Step 5: RIHS01 hash (bash scripts/type_hash.sh <pkg>/msg/<Type>)
- [ ] Step 6: CdrTopicInfo<> specialization (type_name, type_hash, max_serialized_size)
- [ ] Step 7: CHECK_HASH + hashes entry in test/server/test_type_hash.cpp
- [ ] Step 8: bash scripts/verify.sh   (build + type-hash tests)

The five files, in dependency order:

File	What goes in
types/msg/<Type>.h	the POD struct, namespace carla::ros2::msg
types/CdrSerialization.h	include + serialize_cdr/deserialize_cdr overloads
types/CdrTopicInfo.h	include + CdrTopicInfo<msg::Type> specialization
test/server/test_type_hash.cpp	CHECK_HASH(Type) + an entry in hashes
(new carla_msgs only) your .msg	the canonical definition the hash is computed from

Step 1: Check prerequisites

bash scripts/check_env.sh

Steps 3-4: struct and serialization

Rules that matter (full patterns and the sequence/string cases in references/cdr.md):

• Struct lives in namespace carla::ros2::msg; includes only <array>, <vector>, <string>, <cstdint> and sibling msg/*.h — no DDS or Fast-CDR headers.
• Every primitive gets = 0 / = 0.0; fixed arrays are std::array<T,N>, sequences std::vector<T>, nested messages by value.
• Field order and count must mirror the .msg exactly — CDR is positional, so a wrong order produces garbage on the wire with no error anywhere.
• Add the overload pair after the overloads of the types it depends on (CdrSerialization.h is ordered least-to-most dependent, no forward decls).
• Nested msg:: types call their own overload; std::string and std::array go through cdr <<; std::vector<uint8_t> is length-prefixed automatically; a std::vector of structs needs the uint32_t length written by hand and checked against kMaxCdrSequenceElements on read.

Step 5: the RIHS01 hash

# standard type — the .msg is pulled out of osrf/ros:jazzy-desktop for you
bash scripts/type_hash.sh sensor_msgs/msg/Imu

# new carla_msgs type — pass your own definition
bash scripts/type_hash.sh carla_msgs/msg/CarlaSpeedometer ./CarlaSpeedometer.msg

Prints one RIHS01_<64 hex> line (and the definition it hashed, to stderr, so you can eyeball it against your struct). It refuses to print anything that is not in that exact format, because a malformed hash pasted into the source only shows up as a peer-side warning.

Util/ros2/compute_type_hash.sh is broken as shipped (verified 2026-08 on ue4-dev with osrf/ros:jazzy-desktop) — four independent faults, so Step 4 of the upstream doc cannot work:

1. the in-container script runs set -u then sources setup.bash, which dereferences AMENT_TRACE_SETUP_FILES → unbound variable;
2. --log-base is passed after --cmake-args, which swallows it, so CMake gets it → Unknown argument --log-base, 0 packages built;
3. docker run has no --user, so its temp workspace becomes root-owned and its own cleanup rm fails, making the exit code meaningless;
4. it extracts the hash with jq, which that image does not have → the misleading '<type>' not found in <json>.

type_hash.sh runs upstream first and, on failure, retries with a patched temp copy (plus a mounted python jq shim). Your checkout is never modified, and the hash still comes from rosidl's own type-description output. With that in place sensor_msgs/msg/Imu reproduces the value pinned in CdrTopicInfo.h exactly — which is also the best available self-test of this whole procedure. The proper fix is four one-liners upstream.

The hash is what ROS 2 Iron+ compares in the USER_DATA QoS during discovery. Get it wrong or omit it and peers log Failed to parse type hash for topic 'rt/...' — the connection still forms, so this is easy to miss. Return nullptr only for a type with no canonical .msg.

Steps 6-7: registration and test

type_name() is the DDS mangled name <package>::msg::dds_::<TypeName>_ — trailing underscore included; a mismatch means peers never match the endpoint. max_serialized_size() is a preallocation hint in bytes excluding the 4-byte encapsulation header (sizing table in the reference). Then add both test entries — they are what catch a malformed or duplicated hash.

Step 8: verify

bash scripts/verify.sh              # make LibCarla ARGS="--ros2" + make check.LibCarla
BUILD_ONLY=1 bash scripts/verify.sh # compile-only fast loop

Green tests prove the hash is well-formed and unique — not that the wire format is right. For that, publish the type and read it from a real ROS 2 node ([[visualize-ros-rviz]] echo): a field-order bug shows up there and nowhere else.

Examples

Example 1: support an existing ROS type CARLA lacks

User says: "make CARLA publish nav_msgs/Odometry for the ego"

Odometry.h already exists in types/msg/ — check first. If a type is missing, this skill adds it; then [[add-ros-publisher]] does the publishing side. Adding a type alone changes no topic.

Example 2: a new carla_msgs type

User says: "add a CarlaSpeedometer message with the ego speed"

Write CarlaSpeedometer.msg (std_msgs/Header header + float32 speed) → POD → overloads → type_hash.sh carla_msgs/msg/CarlaSpeedometer ./…msg → CdrTopicInfo (carla_msgs::msg::dds_::CarlaSpeedometer_) → tests → verify.

Example 3: the type-hash warning

User says: "peers log Failed to parse type hash for one of my topics"

That type's type_hash() returns nullptr or a malformed string. Recompute with type_hash.sh and paste it in; re-run verify.sh.

Troubleshooting

Problem: compute_type_hash.sh fails inside Docker on colcon build Cause: the .msg depends on a package not present in the jazzy image. Solution: add the dependency to the workspace, or use a newer image (ROS_IMAGE=osrf/ros:<tag>-desktop bash scripts/type_hash.sh …).

Problem: the type builds and publishes, but subscribers get garbage Cause: field order/type mismatch between the POD and the .msg — CDR is positional and carries no field names. Solution: diff the struct against the .msg line by line; the reference has a side-by-side example.

Problem: make check.LibCarla fails on a duplicate hash Cause: the same RIHS01_… string registered for two types (copy-paste). Solution: recompute per type; the uniqueness test exists for exactly this.

Problem: build fails with a Fast-CDR error in the new overload Cause: an overload placed before the types it depends on, or a nested type serialised with cdr << instead of serialize_cdr. Solution: move it below its dependencies; nested msg:: types always recurse.

Outputs

Edited sources in the checkout (five files) and a green check.LibCarla. No topic changes on their own — publishing the new type is [[add-ros-publisher]].

Wire-format detail (CDR encoding, the sizing table, sequence rules, hash semantics) in references/cdr.md.