asterism 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 692f8e51b504a0316c880540228a14a5319b4c05f692390858ceeac92cca0737
-  data.tar.gz: 31c909f9a3244f6e731e916ad40643f1271dcc0bf7b9a1694e3c8235bf97c695
+  metadata.gz: 16a71827f6f79aa024b98f6aa686efa127228644d12f6bef3469dad98d819dac
+  data.tar.gz: b564b747d9cb0dd6d890e86e95cbc04ca75f7d1a55b24490bfd315edfc1cf25a
 SHA512:
-  metadata.gz: e737aae6f7612b8f5463889e962d3811795df2ab5d6baae0359334877759158b901dfc922afdf1425fcac98441a800ec1663d077b6cb741d8a6e1b728998b9ce
-  data.tar.gz: '0048c2a5735d71bb46c1048578f676065f8c82bf3391df4e21feff73a35f1da4cd5f824c718cc00bf764e80f16cf5234ecf6a9dba83623b2d4ec09c66e154890'
+  metadata.gz: bff73ce315295e1d2a4426eef3deda857ba8c77db3c789cb48b0ec489c101cd35633fb6d73fbba31d641ad9d467bbaa7db80aefcf4686af1a798a9f4719a66c4
+  data.tar.gz: 594b310948679e9471dab6853846692c0ffc94a670456b9fcccfe44f7c0e4fbc3cf90fde19e401f992e31897b2b385f7a1856c6a8bef5920b1b6cf75c868e7bf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Katsuhiko Kageyama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,27 @@
+Asterism
+Copyright (c) 2026 Katsuhiko Kageyama
+Asterism's own code is under the MIT License (LICENSE).
+
+This repository also contains material made from ROS 2 message and service
+definitions, which are licensed under the Apache License, Version 2.0
+(data/msgs/LICENSE-Apache-2.0.txt):
+
+- tools/ros2_jazzy/: the .msg / .srv definitions and the package.xml of
+  their packages as distributed with ROS 2 Jazzy
+  (/opt/ros/jazzy/share/<package>/), unchanged, and type_hashes.txt, the
+  type hashes from the type description JSON files of the same packages.
+- data/msgs/: Ruby files generated from those definitions by
+  tools/asterism_msggen.rb (each file names, at its top, the definition and
+  the package it was made from and the package's license).
+- test/msgs/golden_cdr.tsv and test/msgs/test_type_hashes.txt: values
+  computed by ROS 2's tools (rclpy, rosidl) in a ROS 2 Jazzy image.
+
+The ROS 2 packages these come from, all "Apache License 2.0" in their
+package.xml:
+
+- std_msgs, geometry_msgs, sensor_msgs (ros2/common_interfaces)
+- builtin_interfaces, service_msgs (ros2/rcl_interfaces)
+- example_interfaces (ros2/example_interfaces)
+
+Copyright in the definitions belongs to their authors (Open Source Robotics
+Foundation, Inc. and the ROS 2 contributors); see those repositories.

data/README.md

@@ -1,6 +1,408 @@
 # Asterism
 
-Treat many Rubies -- CRuby, mruby on microcontrollers, the browser -- as one
-network of objects, built on Zenoh. Part of the Family mruby project.
+Asterism joins Ruby on PCs, boards (mruby / PicoRuby) and ROS 2 into one
+Zenoh network: Ruby objects on other machines are called like local ones,
+and a Ruby program can be a ROS 2 node (rmw_zenoh's wire format). This
+repository holds the pure Ruby layers, written once for every Ruby:
 
-This release only reserves the name. Nothing works yet.
+| Path | What |
+|---|---|
+| `mrblib/` | The layers: remote objects (`Asterism`), `Asterism::CDR`, `Asterism::ROS`. The source of truth for both forms below |
+| `mrbgem.rake` | The mrbgem `picoruby-asterism` (mruby / PicoRuby): compiles `mrblib/` |
+| `asterism.gemspec`, `lib/` | The CRuby gem `asterism`: `lib/asterism.rb` loads `mrblib/` as it is, `lib/asterism/cruby.rb` adds what CRuby needs |
+| `data/msgs/` | ROS 2 message types generated from ROS 2 Jazzy's definitions (Apache-2.0, see NOTICE) |
+| `tools/` | The type generator `asterism_msggen.rb`, the Jazzy definitions it reads, `ros2_types.rb` (refreshes them from a ROS 2 image) |
+| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions) |
+| `examples/` | CRuby: `node.rb` (objects with a board), `ros2_talker.rb` (Twist and AddTwoInts with ROS 2) |
+
+The Zenoh binding underneath is a separate gem with the same Ruby API on
+each Ruby:
+
+- CRuby: [asterism-zenoh](https://github.com/ruby-asterism/asterism-zenoh)
+  (over zenoh-c)
+- mruby / PicoRuby: [picoruby-asterism-zenoh](https://github.com/ruby-asterism/picoruby-asterism-zenoh)
+  (over zenoh-pico)
+
+Neither gem is on rubygems.org yet (version 0.1.0 builds from these
+repositories with `rake gem`).
+
+## Using it
+
+CRuby (needs CRuby 3.2+ and a C compiler):
+
+```
+gem install asterism          # also installs asterism-zenoh (~> 0.1.0) and msgpack
+ruby -e 'require "asterism"'
+```
+
+`asterism-zenoh` compiles its C extension when it is installed and
+downloads the prebuilt zenoh-c for the machine (x86_64 / aarch64 Linux,
+glibc or musl; x86_64 / arm64 macOS), checked against a pinned sha256; see
+its README for machines without network access. Linux needs glibc 2.34 or
+newer (Ubuntu 22.04, Debian 12 and later) or musl; macOS is supported by the
+build but not yet tested. To install from the repositories instead:
+
+```
+(cd ../asterism-zenoh && rake gem) && rake gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.1.0.gem pkg/asterism-0.1.0.gem
+```
+
+From the working trees, without installing:
+
+```
+ruby -I lib -I ../asterism-zenoh/lib your_script.rb    # after `rake compile` in ../asterism-zenoh
+```
+
+`Asterism::ROS::TYPE_PATH` is `data/msgs` there; add your own directories.
+MessagePack sends every String as str (compatibility mode), as the boards
+do: their MessagePack does not read the bin type.
+
+mruby / PicoRuby: add this repository and picoruby-asterism-zenoh as gems
+(`conf.gem "path/to/asterism"`; a `MessagePack` module with `pack` /
+`unpack` is needed too), and put `data/msgs` on the device's file system at
+`/usr/share/asterism/msgs` (or add the place to
+`Asterism::ROS::TYPE_PATH`). Family mruby does this from pinned commits of
+these repositories.
+
+## Tests
+
+```
+rake                  # both suites
+rake test:msgs        # generator, type hashes, CDR, bundled types (CRuby only; no Zenoh, no docker)
+rake test:objects     # objects and Asterism::ROS between CRuby sessions over a local peer link
+ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects   # the same through a zenohd router
+```
+
+`test:objects` needs asterism-zenoh: built next to this repository
+(`../asterism-zenoh`, its `rake compile`), or `ASTERISM_ZENOH_DIR`, or the
+installed gem.
+
+## Examples
+
+```
+# objects: join the app "demo" of Family mruby's asterism_demo, call a board,
+# and answer its calls (its keys s / a call screen.say / apu.play here)
+ruby examples/node.rb --router tcp/192.0.2.2:7447 [--peer fmruby-aaaaaa]
+
+# ROS 2: geometry_msgs/Twist on /cmd_vel, then AddTwoInts calls
+ruby examples/ros2_talker.rb --router tcp/192.0.2.2:7447 [--service NAME]
+```
+
+## License
+
+MIT (LICENSE) for Asterism's code. The ROS 2 definitions in
+`tools/ros2_jazzy/` (with the package.xml of their packages), the types
+generated from them in `data/msgs/` and the fixtures computed by ROS 2's
+tools in `test/msgs/` are under the Apache License 2.0 (NOTICE,
+`data/msgs/NOTICE`, `data/msgs/LICENSE-Apache-2.0.txt`). Each generated
+type names its package and license at its top. The gem `asterism` is
+therefore `MIT` and `Apache-2.0`, each for its own files.
+
+Not in this repository: the gems Asterism depends on are not bundled.
+`msgpack` (CRuby) and `asterism-zenoh` (the CRuby Zenoh binding, which in
+turn fetches zenoh-c at build time; see its README) are installed by
+RubyGems, and on mruby / PicoRuby the Zenoh binding is the separate mrbgem
+`picoruby-asterism-zenoh`. Their licenses are their own.
+
+---
+
+# The API
+
+The same on every Ruby. The examples use PicoRuby's `sleep_ms`; on CRuby
+write `sleep`. When PicoRuby's `Machine` is there it is used for the clock
+and the short pauses while waiting; otherwise `Time` and `sleep`. Besides
+`Asterism::Zenoh`, the layers need a `MessagePack` module with `pack` /
+`unpack` (the API of the msgpack gem; whichever gem provides it).
+
+```ruby
+# on the machine that has the object
+Asterism.connect("tcp/192.0.2.2:7447", node: "fmruby-bbbbbb", app: "demo")
+Asterism.expose("apu", apu, methods: [:play, :stop])
+loop { Asterism.poll; ... }               # in the update loop
+
+# on another machine
+Asterism.connect("tcp/192.0.2.2:7447", node: "linux", app: "demo")
+apu = Asterism["fmruby-bbbbbb/demo/apu"]  # <node>/<app>/<object>
+apu.play("t120 o4 cdefg")                 # runs there, returns its value
+apu.respond_to?(:play)                    # => true (from the exposed list)
+f = apu.async.play("cde")                 # does not wait
+f.done?; f.value
+Asterism.each("*/*/apu") { |a| a.stop }   # every apu alive now
+Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
+```
+
+## API
+
+| Call | Returns | Raises / notes |
+|---|---|---|
+| `Asterism.connect(locator, node:, app:, mode: nil, listen: nil)` | `Asterism` | `locator`, `mode:`, `listen:` go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to about 1.5 s for that check (a router answers at once). |
+| `Asterism.expose(name, obj, methods:)` | `"<node>/<app>/<name>"` | `methods:` is an Array of names, or a Hash `name => number of arguments` (checked before the call; `-1` or the Array form: any). `ArgumentError` when `obj` has no such public method. Exposing a name again replaces it. |
+| `Asterism.unexpose(name)` | true / false | |
+| `Asterism.poll` | true / false | Call from the update loop: polls Zenoh, answers the calls that came in, follows who is alive. `false` once the connection is closed or lost. |
+| `Asterism[path, timeout_ms = 2000]` | `Proxy` | `path` is `<node>/<app>/<object>` without wildcards (`ArgumentError`). Nothing is sent until a method is called. |
+| `proxy.<method>(*args, **kw)` | the remote return value | Waits for the answer (`timeout_ms`). `RemoteError` when it raised there or could not be called (not exposed: `NoMethodError`; wrong number of arguments: `ArgumentError`; no such object: `NameError`), `Timeout` when no answer came in time (also at once when nobody answers that key), `Disconnected`, `EncodeError` (before anything is sent) for a value MessagePack cannot carry. A block cannot be sent (`ArgumentError`). |
+| `proxy.async.<method>(...)` | `Future` | Sends and returns at once. `EncodeError` / `Disconnected` are raised here. |
+| `future.done?` | true / false | Never waits (`Asterism.poll` moves it on). True once the answer came, the time ran out or the connection closed. |
+| `future.value` | the return value | Waits (polling) if not done; raises like a waiting call. `future.took_ms`: time to the answer. |
+| `proxy.respond_to?(name)` / `proxy.methods` | true / false, `[Symbol]` | From the object's meta (fetched once, `proxy.asterism_refresh` forgets it). `respond_to?` is false when the object does not answer; `methods` raises then. |
+| `proxy.asterism_meta` / `proxy.asterism_path` | Hash, String | `{"methods" => [[name, arity], ...]}` |
+| `Asterism.each(pattern = "**") { \|proxy\| }` | count (Array without a block) | The exposed objects alive now (this application's own included) whose `<node>/<app>/<object>` matches; `*` is one chunk, `**` any number. |
+| `Asterism.nodes` | `[String]` | Node IDs alive now, this one first. |
+| `Asterism.connected?` / `node_id` / `app` / `exposed` / `lost_reason` | | |
+| `Asterism.close` | nil | Withdraws every exposed object. Idempotent. |
+
+Errors: `Asterism::Error` (base, a `StandardError`), `EncodeError`, `RemoteError`
+(`remote_class`, `remote_message`), `Timeout`, `Disconnected`.
+
+### When the connection is lost
+
+Asterism follows `Asterism::Zenoh`: the connection is closed when the router
+(or the only peer) goes away, and is not reopened by itself. From then on
+`Asterism.poll` returns `false`, `connected?` is false, `lost_reason` says
+why, and calls raise `Asterism::Disconnected`. **`Asterism::Zenoh::Error`
+never comes out of Asterism; it is always wrapped in `Disconnected`** (the
+message is kept). The exposed objects are gone with the connection: to go
+on, the application calls `connect` and `expose` again.
+
+## Values
+
+Only what MessagePack carries: `nil`, `true`, `false`, `Integer` (64 bit),
+`Float`, `String`, `Array`, `Hash`. A `Symbol` is sent as a `String` (also
+as a Hash key: keyword arguments arrive as Symbols again). Anything else in
+the arguments raises `EncodeError` before sending; in a return value the
+caller gets `RemoteError` (`Asterism::EncodeError`). Nesting is limited to
+16 levels.
+
+## Keys and encoding
+
+| Key | Zenoh | Payload |
+|---|---|---|
+| `asterism/<node>/<app>/<object>/call` | get / queryable | query: `[method, [args...], {kwargs}]`; reply: `["ok", value]` or `["error", class name, message]` |
+| `asterism/<node>/<app>/<object>/meta` | get / queryable | reply: `{"methods" => [[name, arity], ...]}` (arity `-1` when not declared). The object may be `*` in the query: one reply per object |
+| `asterism/<node>` | liveliness | the node is connected |
+| `asterism/<node>/<app>/<object>` | liveliness | the object is exposed |
+
+One queryable per application (`asterism/<node>/<app>/**`). A call whose
+node or app is a wildcard reaches every application that exposes that
+object, each answering with its own key; `Asterism` itself only sends calls
+to one object.
+
+## How waiting works
+
+Everything is polled; nothing runs behind the application. A call that
+waits keeps polling (pausing 2 ms between polls) and answers the calls that
+come in meanwhile, so two machines calling each other at the same time do
+not lock up. An answered call may itself call and wait; such waits nest at
+most `Asterism::MAX_NESTING` (4) deep, beyond that the call raises `Error`
+(the caller of the outer call gets it as `RemoteError`). While a call
+waits, the rest of that application (drawing, input) waits too; other
+applications do not.
+
+Calls to an object of the same application (`<node>/<app>` is this one) do
+not go out (a Zenoh session does not see its own queryable): they are run
+in place, with the same encoding and checks.
+
+## Stack
+
+A waiting call polls Zenoh on the caller's C stack. Measured on the P4
+(Family mruby, 16 KB application stack): the application idles at 8.1 KB
+used; a waiting call made from the update loop takes it to 10.7 KB, also
+with calls answered while waiting (two machines relaying calls to each
+other). The same call made from an input handler that C calls into (one more
+interpreter entry) reached 12.4 KB; an earlier version of this gem, which
+took zenoh replies through blocks and fetched the meta from inside
+`respond_to_missing?`, overflowed the stack there. Make waiting calls from
+the update loop, or use `async`.
+
+## Limits
+
+- Objects cannot be passed by reference (a return value is a copy), blocks
+  cannot be sent, there are no events (later stages).
+- The node token `asterism/<node>` is shared by every application of that
+  node; when one of them closes, the others still list the node through
+  their objects, but a watcher may see the node token go away.
+- No authentication: a trusted LAN is assumed.
+
+## ROS 2 (rmw_zenoh): `Asterism::ROS` and `Asterism::CDR`
+
+A minimal ROS 2 node that talks to ROS 2 systems using rmw_zenoh (checked
+with ROS 2 Jazzy, rmw_zenoh_cpp 0.2.11, Zenoh 1.8.0), directly on an
+`Asterism::Zenoh::Session`. Pure Ruby, independent of the object layer above
+(no `Asterism.connect`, no MessagePack; only its clock and pause helpers).
+Topics and services. The message and service types are generated from
+`.msg` / `.srv` files (see [Message types](#message-types)) and loaded when
+the application asks for them.
+
+```ruby
+s = Asterism::Zenoh::Session.open("tcp/192.0.2.2:7447")
+node = Asterism::ROS::Node.new(s, "fmruby_talker")       # namespace: "/", domain: 0
+str = Asterism::ROS.require_type("std_msgs/msg/String")
+pub = node.publisher("/chatter", str)
+sub = node.subscription("/chatter_back", "std_msgs/msg/String")  # by name works too
+loop do
+  s.poll
+  pub << { data: "hello" }                               # or pub.publish(str.new(data: "hello"))
+  sub.each_pending { |msg, info| puts "#{info && info.sequence}: #{msg.data}" }
+end
+node.close                                               # or let the session close
+```
+
+Services:
+
+```ruby
+add = Asterism::ROS.require_type("example_interfaces/srv/AddTwoInts")
+node.service("/fmruby/add_two_ints", add) { |req| { sum: req.a + req.b } }
+cli = node.client("/add_two_ints", add)
+loop do
+  node.poll                       # session.poll, then answers the requests
+  res = cli.call(a: 2, b: 3)      # waits (polling), raises Asterism::ROS::Timeout
+  puts res.sum
+  c = cli.call_async(a: 2, b: 3)  # returns at once
+  # ... later updates:
+  puts c.value.sum if c.done?
+end
+```
+
+| Call | Returns | Notes |
+|---|---|---|
+| `Asterism::ROS::Node.new(session, name, namespace: "/", domain: 0, enclave: "/")` | `Node` | Declares the node's liveliness token (`ros2 node list`). `name` has no `/`. |
+| `node.publisher(topic, type, qos: DEFAULT_QOS)` | `Publisher` | `topic` absolute, or relative to the namespace. `type` is a generated type or its ROS name (`"geometry_msgs/msg/Twist"`, loaded with `require_type`); the same for subscriptions, services and clients. Declares the publisher token (`ros2 topic list`). |
+| `pub.publish(msg)` / `pub << msg` | nil / `pub` | `msg` is a message of the type or a Hash of its fields. Puts the CDR payload with rmw_zenoh's attachment (sequence number, time, GID). |
+| `node.subscription(topic, type, qos: DEFAULT_QOS, depth: 16)` | `Subscription` | Subscribes and declares the subscription token. |
+| `sub.each_pending { \|msg, info\| }` | count | `info` is an `Attachment` (`sequence`, `stamp_ns`, `gid`) or nil. Samples that are not valid CDR are skipped and counted in `sub.errors`. |
+| `node.service(name, type, qos: DEFAULT_QOS, depth: 8) { \|req\| response }` | `Service` | Serves `name` (`ros2 service list`). The block gets a `type::Request` and returns a `type::Response` or a Hash of its fields. It runs from `node.poll` (or `service.handle_pending`), never behind the application. A request without rmw_zenoh's attachment, or that does not decode, is counted in `service.errors` and gets no answer. An exception from the block ends that request without an answer and is raised from `node.poll`. `service.handled`: answered so far. |
+| `node.poll(steps = 8)` | true / false | `session.poll(steps)`, then answers the requests waiting for this node's services. Returns what `session.poll` returns. |
+| `node.client(name, type, qos: DEFAULT_QOS)` | `Client` | Declares the client token. |
+| `client.call(request = nil, timeout_ms: 2000, **fields)` | `type::Response` | Sends the request (a `type::Request`, a Hash, or the fields as keywords) and waits, polling the node (its services keep answering). `Asterism::ROS::Timeout` when no response came in time, at once when nobody serves the name; `Asterism::Zenoh::Error` when the session closed. |
+| `client.call_async(request = nil, timeout_ms: 2000, **fields)` | `Call` | Sends and returns at once. `call.done?` never waits (`node.poll` moves it on); `call.value` waits and returns the response or raises like `call`; `call.response` (nil until it came), `call.took_ms`, `call.sequence`. |
+| `node.call(name, type, request = nil, timeout_ms: 2000, **fields)` | `type::Response` | `client.call` through a client made on first use and kept per name. |
+| `node.close` / `pub.close` / `sub.close` / `service.close` / `client.close` | nil | Withdraws the tokens (they also go when the session closes). `node.close` closes everything the node made. |
+| `Asterism::ROS.require_type(name)` | the type | Loads `<pkg>/<msg\|srv>/<Name>.rb` from `Asterism::ROS::TYPE_PATH` (`["/usr/share/asterism/msgs"]`; add directories to it) and returns `Asterism::ROS::<Pkg>::<Name>`. A type already loaded (or defined in Ruby) is returned at once. `UnknownType` when there is no file. |
+| `Asterism::CDR::Writer` / `Reader` | | Plain CDR with the 4-byte header, aligned from the end of the header: `bool int8 uint8 int16 uint16 int32 uint32 int64 uint64 float32 float64 string`, `array(kind, v, fixed, max)`, `bytes`, `structs(type, ...)`. Writes little endian; reads either order. |
+
+What goes on the wire (rmw_zenoh_cpp 0.2.x):
+
+| Item | Form |
+|---|---|
+| Data key | `<domain>/<topic without the outer "/">/<DDS type>/<type hash>`, e.g. `0/chatter/std_msgs::msg::dds_::String_/RIHS01_df668c74...` |
+| Payload | CDR: `00 01 00 00`, uint32 length with the NUL, bytes, NUL |
+| Attachment | int64 sequence, int64 time (ns since the epoch), both little endian, one byte GID length (16), 16 bytes GID: 33 bytes. **Required**: rmw_zenoh drops a sample without it |
+| Node token | `@ros2_lv/<domain>/<zid>/<nid>/<nid>/NN/<enclave>/<namespace>/<node>` |
+| Topic token | `@ros2_lv/<domain>/<zid>/<nid>/<id>/MP` (or `MS`) `/<enclave>/<namespace>/<node>/<topic>/<DDS type>/<type hash>/<qos>` |
+| Service key | `<domain>/<service without the outer "/">/<DDS service type>/<service type hash>`, e.g. `0/add_two_ints/example_interfaces::srv::dds_::AddTwoInts_/RIHS01_e118de6b...`. The type and hash are those of the service, not of its Request / Response |
+| Service request | a get on the service key, target ALL_COMPLETE, no consolidation, payload the request's CDR, attachment as above (the client's sequence number from 1, time, the client's GID) |
+| Service reply | from a **complete** queryable (a non-complete one never sees ALL_COMPLETE queries), on the service key, payload the response's CDR, attachment: the request's sequence number and GID with the server's time. The client pairs reply and request by the sequence number |
+| Service tokens | like topic tokens, with `SS` (server) and `SC` (client) |
+
+In tokens, `/` inside a name is written `%` (`/chatter` is `%chatter`, the
+root namespace `%`). `<zid>` is the Zenoh session ID (`session.zid`).
+`DEFAULT_QOS` (`::,10:,:,:,,`) is rmw_zenoh's form of the default profile:
+reliable, volatile, keep last 10.
+
+Not here (later stages): actions, QoS other than the default (transient
+local needs Zenoh's advanced publisher), name remapping, receiving a type
+the application has not loaded.
+
+## Message types
+
+### Values
+
+A generated message is a plain Ruby class (`Asterism::ROS::Message` is its
+base; the app VM has neither `Data` nor `Struct`). The same code runs on
+CRuby.
+
+```ruby
+Twist = Asterism::ROS.require_type("geometry_msgs/msg/Twist")
+t = Twist.new(linear: { x: 0.1 })     # missing fields take their defaults
+t = Twist.from({ "linear" => { "x" => 0.1 } })   # Hash, String keys too
+t.linear.x                            # => 0.1
+t.angular                             # => #<geometry_msgs/msg/Vector3 {x: 0.0, ...}>
+t.to_h                                # => {linear: {x: 0.1, y: 0.0, z: 0.0}, angular: {...}}
+bytes = Twist.encode(t)               # or Twist.encode(linear: { x: 0.1 })
+Twist.decode(bytes) == t              # => true
+Twist::TYPE_NAME                      # "geometry_msgs::msg::dds_::Twist_"
+Twist::TYPE_HASH                      # "RIHS01_9c45bf16..."
+Asterism::ROS::SensorMsgs::BatteryState::POWER_SUPPLY_STATUS_FULL   # constants
+```
+
+| Field in the .msg | Ruby value | Default |
+|---|---|---|
+| `bool` | true / false | false |
+| integers, `byte`, `char` | Integer (a `uint64` at or above 2**63 reads back negative) | 0 |
+| `float32` / `float64` | Float | 0.0 |
+| `string`, `string<=N` | String (UTF-8 bytes; longer than N raises `ArgumentError` on encode) | "" |
+| a message | that type (a Hash is turned into it) | its defaults |
+| `T[N]`, `T[]`, `T[<=N]` | Array (a wrong length or over the bound raises `ArgumentError` on encode) | N defaults, or [] |
+| `byte[]`, `uint8[]`, `char[]` (any size) | a binary String (an Array of Integers is taken too) | "\0" * N, or "" |
+| `wstring` | not supported: encode / decode raise `NotImplementedError` | |
+
+Defaults written in the .msg (`float64 w 1`) are used. Unknown field names
+raise `ArgumentError`; integers are not range-checked (they wrap).
+
+### The bundled types
+
+Made from ROS 2 Jazzy's definitions, in `data/msgs` (on a board:
+`/usr/share/asterism/msgs`), one file per type:
+std_msgs (Bool, Byte, Char, String, Empty, the integer and float types,
+Header, ColorRGBA, MultiArrayDimension / Layout and every *MultiArray),
+builtin_interfaces (Time, Duration), geometry_msgs (Vector3, Point, Point32,
+Quaternion, Pose, Pose2D, Twist, Accel, Transform, Wrench and their
+*Stamped), sensor_msgs (Imu, BatteryState, Temperature, Range,
+MagneticField, Illuminance, FluidPressure, RelativeHumidity, JointState,
+NavSatStatus, NavSatFix), example_interfaces/srv/AddTwoInts. The list is
+`tools/bundled_types.txt`. Nothing of them is compiled into the mrbgem: an
+application loads what it uses, and each file loads the types it is made of.
+
+### Making types: `tools/asterism_msggen.rb`
+
+CRuby, standard library only, no ROS 2 installation needed (only the
+`.msg` / `.srv` files of the packages involved):
+
+```
+# a type of an installed ROS 2 (and the types it uses)
+ruby tools/asterism_msggen.rb -I /opt/ros/jazzy/share -o out geometry_msgs/msg/Twist
+# your own package (my_pkg/msg/Foo.msg; -I for the packages it refers to)
+ruby tools/asterism_msggen.rb -I /opt/ros/jazzy/share -o out path/to/my_pkg/msg/Foo.msg
+# print the type hashes
+ruby tools/asterism_msggen.rb -I share --hash example_interfaces/srv/AddTwoInts
+# compare the hashes with the type description JSON ROS 2 installs
+ruby tools/asterism_msggen.rb -I /opt/ros/jazzy/share --check-json /opt/ros/jazzy/share sensor_msgs/msg/Imu
+```
+
+`-I` directories are laid out like a ROS 2 `share`: `<pkg>/msg/*.msg`,
+`<pkg>/srv/*.srv`. The output is `<out>/<pkg>/<msg|srv>/<Name>.rb`; copy it
+to the device (`/usr/share/asterism/msgs` or a directory added to
+`Asterism::ROS::TYPE_PATH`), or put the output directory in `TYPE_PATH` on
+CRuby. A service's type hash needs `service_msgs/msg/ServiceEventInfo` and
+`builtin_interfaces/msg/Time` under `-I` (every ROS 2 `share` has them).
+
+The type hash (RIHS01) is computed the way ROS 2 Jazzy does
+(`rosidl_generator_type_description`): the type and every type it refers
+to, each as `{type_name, fields: [{name, type: {type_id, capacity,
+string_capacity, nested_type_name}}]}` without default values, the referred
+ones sorted by name, written as Python's `json.dumps(..., separators=(", ",
+": "))`, then SHA-256. A service's description is `request_message`,
+`response_message` and `event_message` (`<Name>_Event`: `info`, and
+`request` / `response` as sequences of at most one). Other ROS 2 versions
+may change the rules; regenerate and check with `--check-json` against that
+version.
+
+`tools/ros2_jazzy/` holds the Jazzy definitions of the bundled types and
+the hashes from Jazzy's JSON (`type_hashes.txt`) that the tests
+(`rake test:msgs`) compare with. `tools/ros2_types.rb` refreshes both, and
+`data/msgs`, from a ROS 2 Jazzy docker image (`rake types:refresh` with
+`ASTERISM_ROS2_IMAGE`; `rake types:check` only compares). The definitions
+are from ros2/common_interfaces, ros2/rcl_interfaces and
+ros2/example_interfaces (Apache License 2.0, see NOTICE).
+
+### Loading
+
+On mruby, `require_type` reads the file and evaluates it in the
+application's VM (`Kernel#eval`); PicoRuby's `require` would run each file
+in a Sandbox task that stays for the life of the VM. On CRuby it uses
+`require`. Measured on the P4 (Family mruby, a 1 MB VM pool):
+geometry_msgs/Twist with Vector3 15.3 KB, sensor_msgs/Imu with Header,
+Time and Quaternion 32.8 KB more, std_msgs/Float32MultiArray with its
+layout types 20.0 KB more (68 KB for nine files, 340 ms). Evaluating a file
+compiles it on the caller's stack (about 2.5 KB deeper than the update
+loop); load the types in `on_create`, not in a deep call chain.