asterism 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd2f9fe700f5ca0b88f98fc6598217c87be3257e31a655d33ba710f9260b76ea
-  data.tar.gz: '0943fd816e28b2a60c5d812095d5c87d9ac0f1a8d1a0aaf7428989f34526aeb5'
+  metadata.gz: ba14899dd37f9c4c21e148a2256d71545785da6f61a1f8f6701e2d0d189e9061
+  data.tar.gz: 207e08ed177ffa93cd5c7173a84c31f519f59c8e076c6c641ccaa8db27712ea9
 SHA512:
-  metadata.gz: 86426bc1893654601c5a7b9234b09d82b10c6e8260553160f2484b2665ec0eba6bf4293fa1994f88b814997cbad2c69af2d4b2a492f034303ee20c61145f3f43
-  data.tar.gz: 387f4b1de6234f98b3c4b71ce0aee0d6f4d70ec32250350786cff73ec4cf1d500a64277b90f389f2544465409279aba601ac67fd0b3470919f0902727a21334e
+  metadata.gz: de0f85b8c36d4b3c991603004f151ea68952bd7fcc7fdbc76b992af80505b45be3612c5975e509e4f1415f553db8d91ea94940817c00768705bdbf1a011d45e6
+  data.tar.gz: df7634a6c9453fb647c0f148199ff056c646451e3c839ac5cf02704db0ee7dfa7508d8aabdd9fde8005b8909dd6c7217f2d2b96a6e066ac6895d39d9a2af9481

data/CHANGELOG.md

@@ -6,6 +6,81 @@ the earlier ones are only in this repository. From 0.4.0 the two Zenoh
 bindings (asterism-zenoh, picoruby-asterism-zenoh) carry the same minor
 version (a patch release of one may come without the other).
 
+## 0.6.0
+
+One connection for everything and a lighter `Asterism.poll`; every 0.5.x
+call works as before. Needs asterism-zenoh / picoruby-asterism-zenoh 0.4.0
+(unchanged).
+
+Added
+
+- `Asterism.session` (README "One connection"): the Zenoh session of
+  `Asterism.connect` (an `Asterism::Zenoh::Session`), for put, subscribe, a
+  ROS 2 node (`Asterism::ROS::Node.new(Asterism.session, ...)`) and the rest
+  of the Zenoh API on the same connection. `Disconnected` when not
+  connected. The session stays Asterism's: its `close` does nothing (it
+  warns once); `Asterism.close` and a lost connection close it, with
+  everything declared on it. A router that lets a one-time password in
+  once now takes such an application, and its ROS 2 node has the node's
+  Zenoh ID (a console draws it inside the node).
+- The CRuby API: `net.session`, the same session as a `Zenoh::Connection`
+  on the `Net`'s receiving thread (`shared?`; its `close` does nothing);
+  `Asterism::ROS::Connection.new(net.session)` makes ROS 2 nodes on it, and
+  its `close` withdraws only its nodes. `Zenoh::Connection#shared?`.
+  `ROS::Node#close` on a `ROS::Connection` also stops polling the node.
+- `rake bench:poll` (`test/bench_poll.rb`): the time and the allocations
+  of one `Asterism.poll` by the number of nodes and objects.
+- Tests: `test/test_session.rb`, `test/test_api_session.rb`, and on mruby
+  `host_test/test_session.rb` with `host_test/peer.rb` (the mruby test
+  build adds mruby-eval for the ROS 2 type files).
+
+Changed
+
+- `Asterism.poll` does less when nothing came: each queue (calls, profile
+  queries, liveliness) is read only when its count is not zero, and the
+  list of nodes and the comparison behind `on_join` / `on_leave` are made
+  again only after a liveliness change, with Hashes instead of `include?`.
+  The behaviour is the same (the order and number of the `on_join` /
+  `on_leave` calls, the order of `Asterism.nodes`). With 4 other nodes and
+  5 objects, a poll in which nothing changed: CRuby 3.2 us and 49
+  allocations -> 0.6 us and 7; mruby (host) 14-17 us -> 2.2 us.
+  `Asterism.each` drops duplicates with a Hash.
+
+## 0.5.0
+
+Node profiles; every 0.4.x call works as before. Needs asterism-zenoh /
+picoruby-asterism-zenoh 0.4.0 (unchanged).
+
+Added
+
+- Node profiles (README "Profiles"): `Asterism.profile(kind:, name:, host:,
+  icon:)` sets this node's profile (the fields given; the rest stay) and
+  returns it, `Asterism.profile` returns it, `Asterism.profile_of(node,
+  icon: true, timeout: 2.0)` asks another node's (nil when it does not
+  answer). The CRuby API: `net.profile`, `net.profile_of`. Answered on
+  `asterism/<node>/@profile` (a queryable of every connected application,
+  MessagePack Hash: `kind`, `host`, `name`, `icon`, `icon_hash`; the
+  parameter `icon=0` leaves the icon out), and put on the same key without
+  the icon at connect and on each change.
+- Defaults: `kind` is `cruby` on CRuby and `picoruby` on mruby / PicoRuby;
+  the icon is the file at `Asterism.default_icon_path` when it is there:
+  the gem's `data/icon.png` on CRuby (new; a ruby, 32x32), and
+  `/usr/share/asterism/icon.png` on the boards.
+- `Asterism::Profile`: `png_info` (the icon checks: PNG signature, chunks
+  from IHDR to IEND, 8 KB, 256x256; and `icon_hash`, the Adler-32 of the
+  chunks' CRCs), `check` (cleans a received profile: an icon that does not
+  pass is dropped), the limits as constants.
+- `rake test:mruby` and `host_test/`: the shared layer on mruby (built with
+  picoruby-asterism-zenoh, MRB_UTF8_STRING as on the boards), profiles
+  between two mruby processes. CI runs it.
+
+Changed
+
+- The "Ruby profile" (0.4.0) is now called the Ruby feature table, so that
+  it is not taken for a node's profile: `docs/ruby_profile.md` is
+  `docs/ruby_features.md`. The probes' directory `profile/` and its code
+  keep their names.
+
 ## 0.4.1
 
 Additions and a fix; every 0.4.0 call works as before. Needs

data/README.md

@@ -10,10 +10,12 @@ repository holds the pure Ruby layers, written once for every Ruby:
 | `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, `lib/asterism/cruby/` the CRuby API (CRuby only) |
+| `data/icon.png` | CRuby's default profile icon (32x32 PNG; [Profiles](#profiles)) |
 | `data/msgs/` | ROS 2 message types generated from ROS 2 Jazzy's definitions (Apache-2.0; tf2_msgs BSD-3-Clause; 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), `test_api_*.rb` (the CRuby API) |
-| `examples/` | CRuby: `node.rb` (objects with a board), `node_polled.rb` (the same with the portable API of the boards), `ros2_talker.rb` (topics, a timer, services with ROS 2), `zenoh.rb` (plain Zenoh) |
+| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_profile.rb` (node profiles), `test_session.rb` (`Asterism.session`, `on_join` / `on_leave`), `test_api_*.rb` (the CRuby API), `bench_poll.rb` (`rake bench:poll`) |
+| `host_test/` | `rake test:mruby`: the shared layer on mruby (profiles between two mruby processes; `Asterism.session`, `on_join` / `on_leave` and the time of a poll against `peer.rb`) |
+| `examples/` | CRuby: `node.rb` (objects with a board), `node_polled.rb` (the same with the portable API of the boards), `ros2_talker.rb` (topics, a timer, services with ROS 2), `ros2_rover.rb` (drive a ROS 2 robot: `/cmd_vel`, `/odom`, `/imu`), `zenoh.rb` (plain Zenoh), `mujoco/` (MuJoCo run from CRuby through Fiddle, its robot exposed as Asterism objects; see its README) |
 
 The Zenoh binding underneath is a separate gem with the same Ruby API on
 each Ruby:
@@ -35,7 +37,12 @@ Both gems are on rubygems.org (`gem install asterism` installs
 asterism-zenoh too). What changed in each version is in
 [CHANGELOG.md](CHANGELOG.md); 0.4.0 is the first step toward 1.0
 ([docs/api_review.md](docs/api_review.md)) and only adds and deprecates
-(see [Deprecations and 1.0](#deprecations-and-10)).
+(see [Deprecations and 1.0](#deprecations-and-10)); 0.5.0 adds node
+profiles ([Profiles](#profiles): what a node runs on, where, a name and an
+icon); 0.6.0 adds `Asterism.session`
+([One connection](#one-connection-asterismsession): the object layer's
+session for plain Zenoh and ROS 2 too) and makes `Asterism.poll` cheap when
+nothing changed.
 
 ## Which API?
 
@@ -55,6 +62,7 @@ Entry points and what they give:
 | `Asterism::Zenoh::Session.open` | a `Session` (portable) | zenoh-c / zenoh-pico |
 | `Asterism::Zenoh.open` | a `Zenoh::Connection` (CRuby) | `c.session` is the `Session` |
 | `Asterism.connect` | `Asterism` itself (portable; one connection per process or VM), or a `Net` to the block (CRuby) | a `Session` of its own |
+| `Asterism.session` | that `Session` (portable), for put, subscribe and a ROS 2 node on the same connection; `net.session` is it as a `Zenoh::Connection` (CRuby) | the object layer's (Asterism closes it) |
 | `Asterism::ROS::Node.new(session, ...)` | a `Node` (portable) | the `Session` given |
 | `Asterism::ROS.connect` | a `ROS::Connection` (CRuby) | `ros.zenoh` is the `Zenoh::Connection` |
 
@@ -83,7 +91,7 @@ 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.4.0.gem pkg/asterism-0.4.0.gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.0.gem pkg/asterism-0.6.0.gem
 ```
 
 From the working trees, without installing:
@@ -111,8 +119,18 @@ rake test:msgs        # generator, type hashes, CDR, bundled types (CRuby only;
 rake test:objects     # objects and Asterism::ROS between CRuby sessions over a local peer link
 rake test:api         # the CRuby API (blocks, receiving threads, Enumerators)
 ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects test:api   # the same through a zenohd router
+rake test:mruby       # the shared layer on mruby (builds mruby; not part of `rake`)
+rake bench:poll       # the time and allocations of one Asterism.poll by nodes and objects (prints a table)
 ```
 
+`test:mruby` builds mruby with picoruby-asterism-zenoh and this gem
+(MRB_UTF8_STRING, as on Family mruby's boards) and runs `host_test/`: two
+mruby processes over a local peer link. It takes the mruby and zenoh-pico
+pinned by a picoruby-asterism-zenoh checkout next to this one (its
+`rake mruby:fetch zenoh:fetch`), or `PICORUBY_ASTERISM_ZENOH_DIR` /
+`MRUBY_DIR`. A small MessagePack for the test is in
+`host_test/msgpack.rb` (the boards bring their own).
+
 `test:objects` and `test:api` need asterism-zenoh: built next to this repository
 (`../asterism-zenoh`, its `rake compile`), or `ASTERISM_ZENOH_DIR`, or the
 installed gem. The tests run with deprecated calls raising
@@ -131,6 +149,17 @@ ruby examples/node_polled.rb --router tcp/192.0.2.2:7447    # the same, polled
 # /cruby/add_two_ints served, AddTwoInts calls
 ruby examples/ros2_talker.rb --router tcp/192.0.2.2:7447 [--service NAME]
 
+# ROS 2: drive a robot (made for family-mruby's MuJoCo rover,
+# docker-compose.mujoco.yml): 1 m forward and 90 degrees left by /odom,
+# compared with /ground_truth/odom; or the keyboard
+ruby examples/ros2_rover.rb --router tcp/192.0.2.2:7447 [--keys]
+
+# MuJoCo from CRuby (Fiddle), the robot as objects mujoco/rover/{drive,state,world};
+# the MuJoCo release is fetched into examples/mujoco/vendor (examples/mujoco/README.md)
+ruby examples/mujoco/fetch.rb
+ruby examples/mujoco/rover.rb --router tcp/192.0.2.2:7447
+ruby examples/mujoco/drive.rb --router tcp/192.0.2.2:7447 [--keys]
+
 # plain Zenoh: run two with different --name
 ruby examples/zenoh.rb --router tcp/192.0.2.2:7447 --name pc1
 ```
@@ -227,6 +256,8 @@ end
 | `net.each(pattern = "**")` | the proxies alive now; an Enumerator without a block. With a block it returns their number (1.0: `self`, as Ruby's `each` does; `net.count` is the number) |
 | `net.on_join { \|node\| }` / `net.on_leave { \|node\| }` | `Asterism.on_join` / `on_leave` of the portable API (the same blocks, told from `Asterism.poll`), here on the receiving thread; what they raise goes to `on_error`. `net.off_join(proc)` / `off_leave(proc)` remove one |
 | `net.start` / `stop` / `run` / `running?` / `on_error` | as for Zenoh. A method of an exposed object that raises is answered to its caller as a `RemoteError`, as before; `on_error` gets what `on_join` / `on_leave` raise |
+| `net.profile(**fields)` / `net.profile_of(node, icon: true, timeout: 2.0)` | `Asterism.profile` / `profile_of` ([Profiles](#profiles)); `profile_of` waits for the receiving thread's ticks while it runs |
+| `net.session` | `Asterism.session` as a `Zenoh::Connection` (`subscribe { }`, `put`, `publisher`, ...) on this receiving thread: its blocks run there, between the calls answered. `shared?` is true; its `close` does nothing and `start` / `stop` / `run` are the `Net`'s. A ROS 2 node on it: `Asterism::ROS::Connection.new(net.session).node("name")`. See [One connection](#one-connection-asterismsession) |
 | `net.nodes`, `node_id`, `app`, `connected?`, `lost_reason`, `poll`, `close` | |
 
 ### Over TLS (a router on the internet)
@@ -282,6 +313,7 @@ end
 | `node.call(name, type, request = nil, request:, timeout: 2.0, **fields)` | waits for the response. Here `timeout:` is always the time limit (see [Reserved keywords](#reserved-keywords)) |
 | `ros.spin` (`run`) / `start` / `stop` / `running?` / `on_error` / `close` | |
 | `ros.zenoh` | the `Asterism::Zenoh::Connection` underneath (same receiving thread) |
+| `Asterism::ROS::Connection.new(net.session, domain: 0)` | nodes on the object layer's session (the same Zenoh ID as the objects), spun by the `Net`'s receiving thread. Its `close` withdraws its nodes only |
 
 `type` is a generated type or its name (`"geometry_msgs/msg/Twist"`).
 Messages and `Attachment` take part in pattern matching (`deconstruct_keys`,
@@ -387,7 +419,7 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 | `Asterism.connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: 1.5)` | `Asterism` | `locator`, `mode:`, `listen:` (and `config:` / `connect_timeout:` when given, CRuby only: TLS and the rest of zenoh's configuration; the boards raise `ArgumentError`) 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 `check_timeout:` seconds for that check (a router answers at once; give more over a slow relay). Returns the module itself: on a board the module is the connection (one per application). The default is plain text without authentication; see [Over TLS](#over-tls-a-router-on-the-internet). |
 | `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 and calls the `on_join` / `on_leave` blocks. `false` once the connection is closed or lost. |
+| `Asterism.poll` | true / false | Call from the update loop: polls Zenoh, answers the calls that came in, follows who is alive and calls the `on_join` / `on_leave` blocks. `false` once the connection is closed or lost. Cheap when nothing came (0.6.0): each queue is looked at by its count, and the list of nodes is made again only after a liveliness change. |
 | `Asterism.on_join { \|node\| }` / `Asterism.on_leave { \|node\| }` | `Asterism` | Another node appeared (its node token or one of its objects) / is gone (no token and no object left). The nodes there already join on the first polls after connecting; when the connection is lost, every node known until then leaves (on the next `Asterism.poll`). The blocks run from `Asterism.poll` only, never from the polling inside a waiting call; what they raise comes out of `Asterism.poll`. Each call adds a block; `Asterism.off_join(proc)` / `off_leave(proc)` remove one; `Asterism.close` forgets them (a lost connection does not). |
 | `Asterism[path, timeout: 2.0]` | `Proxy` | `path` is `<node>/<app>/<object>` without wildcards (`ArgumentError`). `timeout:` (seconds) or `timeout_ms:` is the time limit of its calls. Nothing is sent until a method is called. |
 | `proxy.<method>(*args, **kw)` | the remote return value | Waits for the answer (the proxy's time limit). `RemoteError` when it raised there or could not be called (not exposed: `NoMethodError`; wrong number of arguments: `ArgumentError`; no such object: `NameError`), `TimeoutError` 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`). |
@@ -399,7 +431,115 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 | `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. 1.0 returns the proxies from the block form instead of their number (Ruby's `each` returns its receiver); write `Asterism.each(pattern).size` for the count. |
 | `Asterism.nodes` | `[String]` | Node IDs alive now, this one first. |
 | `Asterism.connected?` / `node_id` / `app` / `exposed` / `lost_reason` | | |
+| `Asterism.session` | `Asterism::Zenoh::Session` | The connection's own session, for put / subscribe / a ROS 2 node on the same connection ([One connection](#one-connection-asterismsession)). The same object until the connection closes. `Disconnected` when not connected. Its `close` does nothing (warns once); `Asterism.close` closes it. |
 | `Asterism.close` | nil | Withdraws every exposed object. Idempotent. |
+| `Asterism.profile(kind:, name:, host:, icon:)` / `Asterism.profile` | Hash | This node's profile: sets the fields given and returns it; without arguments, returns it. See [Profiles](#profiles). |
+| `Asterism.profile_of(node, icon: true, timeout: 2.0)` | Hash or nil | Another node's profile, nil when it does not answer (an older version, a ROS 2 node). |
+
+## Profiles
+
+A node tells what it is (0.5.0): what Ruby runs it, where, a display name
+and an icon. A console draws it with that; anyone can ask.
+
+```ruby
+Asterism.profile(name: "Rover", icon: File.binread("rover.png"))   # this node's (any time)
+Asterism.profile
+# => {"kind" => "cruby", "name" => "Rover", "icon" => "\x89PNG...", "icon_hash" => "2a8c0626"}
+Asterism.profile_of("fmruby-aaaaaa")
+# => {"kind" => "family_mruby", "host" => "atoms3r", "icon" => "\x89PNG...", "icon_hash" => "..."}
+Asterism.profile_of("fmruby-aaaaaa", icon: false)   # the same without the icon bytes
+Asterism.profile_of("an-older-node")                 # => nil
+```
+
+| Field | Value | Default |
+|---|---|---|
+| `kind` | what Ruby runs the node: `family_mruby`, `picoruby`, `cruby`, `console` (a lower-case word: `a-z`, `0-9`, `_`, up to 32 bytes; other words are allowed) | `cruby` on CRuby, `picoruby` on mruby / PicoRuby; Family mruby's firmware sets `family_mruby` |
+| `host` | where it runs, e.g. `atoms3r`, `tab5`, `p4nano`, `browser`, `sim` (up to 32 bytes) | none; Family mruby's firmware sets it from the board |
+| `name` | a display name (up to 64 bytes) | none |
+| `icon` | the bytes of a PNG: at most 8 KB and 256x256 (32x32 is the size meant). PNG only: an SVG can carry scripts | the file at `Asterism.default_icon_path` when it is there: on CRuby the gem's `data/icon.png` (a ruby), on the boards `/usr/share/asterism/icon.png` |
+| `icon_hash` | set by Asterism, never given: the icon's summary (8 hex digits: the Adler-32 of the PNG's chunk CRCs, so a board computes it from a few bytes) | |
+
+- **Setting.** `Asterism.profile(**fields)` changes the fields given and keeps
+  the others; `nil` leaves `name` / `host` out, goes back to the default
+  `kind`, and means no icon for `icon:`. It raises `ArgumentError` for a
+  field it does not accept (an unknown name, a `kind` that is not a word, an
+  icon that is not a PNG, larger than 8 KB or 256x256). It may be called
+  before connecting and at any time after; the profile belongs to the
+  process (the VM on a board) and survives `close`. A firmware can set its
+  defaults with the same call before the application runs (Family mruby
+  sets `kind`, `host` and, through `/usr/share/asterism/icon.png`, the icon).
+- **Reading.** `Asterism.profile_of(node)` asks `asterism/<node>/@profile`
+  and waits like a call (`timeout:` / `timeout_ms:`); this node's own comes
+  without the network. The answer is cleaned (`Asterism::Profile.check`):
+  only the fields above, each checked; an icon that is not an acceptable
+  PNG is dropped with its hash, an answer without a valid `kind` is `nil`.
+  `icon: false` asks without the icon (the parameter `icon=0`): a reader
+  that already has the icon of that `icon_hash` asks this way.
+- **Following.** At each connect and at each change while connected, the
+  node also puts its profile without the icon on `asterism/<node>/@profile`;
+  subscribe to `asterism/*/@profile` to follow the changes (and fetch the
+  icon again only when `icon_hash` changed). Older nodes neither answer nor
+  put.
+- **Several applications of one node** (a board running two): each answers
+  for the node, and `profile_of` takes the first answer. Give them the same
+  profile (Family mruby's firmware defaults are the same in each), or set it
+  in one and read the notices, where the last change wins.
+- `Asterism::Profile.png_info(bytes)` gives `[width, height, icon_hash]` of
+  an acceptable PNG (nil otherwise), for a tool that wants to check an icon
+  first.
+
+## One connection: `Asterism.session`
+
+An application that also puts, subscribes or runs a ROS 2 node uses the
+object layer's own session for it (0.6.0) instead of opening a second one:
+
+```ruby
+Asterism.connect("tcp/192.0.2.2:7447", node: "fmruby-aaaaaa", app: "game")
+Asterism.expose("othello", game, methods: [:move, :state])
+s = Asterism.session                                    # an Asterism::Zenoh::Session
+s.put("asterism/fmruby-aaaaaa/game/othello/state", MessagePack.pack(state))
+moves = s.subscribe("asterism/*/game/othello/state")    # moves.each_pending in the update loop
+node = Asterism::ROS::Node.new(s, "brain")               # a ROS 2 node with the same Zenoh ID
+cmd = node.publisher("/cmd_vel", "geometry_msgs/msg/Twist")
+# update loop: Asterism.poll; node.poll
+```
+
+CRuby API:
+
+```ruby
+Asterism.connect(router, node: "mypc", app: "demo") do |net|
+  net.session.subscribe("asterism/*/game/**") { |sample| p sample.key }   # on the receiving thread
+  ros = Asterism::ROS::Connection.new(net.session)
+  ros.node("brain").subscribe("/odom", "nav_msgs/msg/Odometry") { |odom| puts odom.pose.pose.position.x }
+  net.run
+end
+```
+
+- **Why one.** A router that lets each pass in once (a one-time password
+  at a `wss://` door) lets only the first session in; and a ROS 2 node on
+  the object layer's session has the node's Zenoh ID, so a console draws it
+  inside the node.
+- **Who closes it.** The session is Asterism's. `Asterism.session.close`
+  (and `net.session.close`) does nothing but warn once, so a library handed
+  the session cannot break the connection. `Asterism.close`, the end of the
+  connect block and a lost connection close it, and with it everything
+  declared on it: the application's subscribers, publishers, ROS 2 nodes.
+  Close those yourself when you are done with them earlier (`sub.close`,
+  `node.close`; on CRuby `ros.close` withdraws its nodes and leaves the
+  rest).
+- **After a lost connection** (`Asterism.poll` returned false), connect
+  again, take `Asterism.session` again (a new object) and declare again
+  what you had on the old one.
+- **Polling.** `Asterism.poll` polls the session; `node.poll` polls it too
+  and only then serves the node. Each subscriber, queryable and node keeps
+  what came for it, so the order does not matter and nothing is taken from
+  another. Your own `put` does not come back to your own subscriber on the
+  same session.
+- **Keys.** Keep your keys out of the object layer's: `asterism/<node>/<app>/**`
+  is answered by its queryable (`get` there is a call), `asterism/<node>` and
+  `asterism/<node>/<app>/<object>` are its liveliness tokens. Putting under
+  `asterism/<node>/<app>/<object>/<anything>` (a state, a log) is fine:
+  puts and subscriptions do not meet queryables or liveliness.
 
 ## Errors
 
@@ -441,6 +581,7 @@ is closed (1.0: `Disconnected`, as the object layer).
 | Receiving interval of the CRuby API | 2 ms | `interval:` |
 | Calls waiting inside each other | 4 | `MAX_NESTING` |
 | Encoding depth of a value | 16 | `Codec::MAX_DEPTH` |
+| A profile icon | 8 KB, 256x256, PNG only | `Asterism::Profile::ICON_MAX`, `ICON_SIDE_MAX` |
 | `get` consolidation | `:none` (every reply; zenoh's own default is `:auto`, but services and the object layer want every reply) | `consolidation:` |
 
 ### Queues
@@ -511,7 +652,9 @@ Asterism follows `Asterism::Zenoh`: the connection is closed when the router
 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.
+on, the application calls `connect` and `expose` again, and declares again
+what it had on `Asterism.session` (subscribers, ROS 2 nodes; the old
+session is closed, its entities raise `Zenoh::ClosedError`).
 
 ## Values
 
@@ -530,8 +673,10 @@ caller gets `RemoteError` (`Asterism::EncodeError`). Nesting is limited to
 | `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 |
+| `asterism/<node>/@profile` | get / queryable, and put | query (parameter `icon=0` for no icon): reply the node's profile, a Hash (`kind`, `host`, `name`, `icon`, `icon_hash`; [Profiles](#profiles)). The node also puts the profile without the icon at connect and on each change. `@profile` is a verbatim chunk, so `asterism/**` does not match it: the object layer's wildcards never see it. An application's own profile would go at `asterism/<node>/<app>/@profile` (not in 0.6.0) |
 
-One queryable per application (`asterism/<node>/<app>/**`). A call whose
+One queryable per application (`asterism/<node>/<app>/**`), and one for the
+profile (`asterism/<node>/@profile`). 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.
@@ -601,7 +746,7 @@ nested type (`geometry_msgs/msg/Twist`) at start-up took 0.6 KB more.
   different on Family mruby's PicoRuby: `^x` of an outer local inside a
   block, `^(expr)`, `Const[...]` and `**rest` next to another key. The full
   list of what the boards' Ruby can and cannot do is in
-  [docs/ruby_profile.md](docs/ruby_profile.md).
+  [docs/ruby_features.md](docs/ruby_features.md) (the Ruby feature table).
 
 ## ROS 2 (rmw_zenoh): `Asterism::ROS` and `Asterism::CDR`
 

data/lib/asterism/cruby/objects.rb

@@ -26,7 +26,8 @@ module Asterism
   # The portable API, entered under LOCK. Prepended to the Asterism module's
   # singleton class, so the shared methods themselves are not changed.
   module Locked
-    %i[expose unexpose poll nodes [] call_async meta connected? exposed on_join on_leave off_join off_leave].each do |m|
+    %i[expose unexpose poll nodes [] call_async meta connected? exposed on_join on_leave off_join off_leave
+       profile profile_async session].each do |m|
       define_method(m) do |*args, **kw, &blk|
         ::Asterism::LOCK.synchronize { super(*args, **kw, &blk) }
       end
@@ -129,6 +130,21 @@ module Asterism
       @runner.add { ::Asterism.poll ? 0 : false }
     end
 
+    # Asterism.session as a Zenoh::Connection (the block API of
+    # Asterism::Zenoh.open) on the same receiving thread as the objects:
+    # subscribe / queryable blocks run there, between the calls answered.
+    # For a ROS 2 node on the same session:
+    # Asterism::ROS::Connection.new(net.session).node("name"). The session
+    # stays Asterism's: net.session.close does nothing (shared?), net.close
+    # closes it. Disconnected when not connected.
+    def session
+      ::Asterism::LOCK.synchronize do
+        s = ::Asterism.session
+        @session = nil if @session && !@session.session.equal?(s)
+        @session ||= ::Asterism::Zenoh::Connection.new(s, runner: @runner)
+      end
+    end
+
     def node_id = ::Asterism.node_id
     def app = ::Asterism.app
     def connected? = ::Asterism.connected?
@@ -147,6 +163,17 @@ module Asterism
       ::Asterism.unexpose(name)
     end
 
+    # Asterism.profile: this node's profile (with keywords, sets fields).
+    def profile(**fields)
+      ::Asterism.profile(**fields)
+    end
+
+    # Asterism.profile_of: another node's profile, or nil. Waits like a
+    # call (for the receiving thread's ticks while it runs).
+    def profile_of(node, icon: true, timeout: nil, timeout_ms: nil)
+      ::Asterism.profile_of(node, icon: icon, timeout: timeout, timeout_ms: timeout_ms)
+    end
+
     # A proxy for <node>/<app>/<object>; timeout: in seconds (or
     # timeout_ms:).
     def [](path, timeout: nil, timeout_ms: nil)

data/lib/asterism/cruby/ros.rb

@@ -95,12 +95,15 @@ module Asterism
         self
       end
 
-      # Stops spinning, withdraws the nodes and closes the session.
+      # Stops spinning, withdraws the nodes and closes the session. On
+      # Asterism's session (ROS::Connection.new(net.session)) it only
+      # withdraws the nodes: the receiving thread and the session stay the
+      # object layer's.
       def close
-        runner.stop
+        runner.stop unless @zenoh.shared?
         @nodes.each { |n| n.close rescue ::Asterism::Zenoh::Error }
         @nodes = []
-        @zenoh.close
+        @zenoh.close unless @zenoh.shared?
         nil
       end
 
@@ -142,8 +145,17 @@ module Asterism
 
       def asterism_runner = @asterism_runner
 
+      # Withdraws the node and stops polling it.
+      def close
+        @asterism_runner.lock.synchronize do
+          super
+          @asterism_runner.remove(@asterism_task) if @asterism_task
+          @asterism_task = nil
+        end
+      end
+
       # The calls that change the node take the connection's lock.
-      %i[subscription client close every cancel_timer].each do |m|
+      %i[subscription client every cancel_timer].each do |m|
         define_method(m) do |*args, **kw, &blk|
           @asterism_runner.lock.synchronize { super(*args, **kw, &blk) }
         end

data/lib/asterism/cruby/zenoh.rb

@@ -158,11 +158,29 @@ module Asterism
     class Connection
       attr_reader :session, :runner
 
-      def initialize(session, interval: Runner::DEFAULT_INTERVAL)
+      # runner: an existing Runner to receive on instead of a new one
+      # (Asterism::Net#session gives the object layer's: the session and
+      # its receiving thread are Asterism's, see shared?). @api private
+      def initialize(session, interval: Runner::DEFAULT_INTERVAL, runner: nil)
         @session = session
-        @runner = Runner.new(session, interval: interval, name: "zenoh")
-        # The first task: false (the runner stops) once the session closed.
-        @runner.add { @session.poll ? 0 : false }
+        if runner
+          @runner = runner
+          @shared = true
+        else
+          @runner = Runner.new(session, interval: interval, name: "zenoh")
+          # The first task: false (the runner stops) once the session closed.
+          @runner.add { @session.poll ? 0 : false }
+          @shared = false
+        end
+      end
+
+      # True for the Connection of Asterism's own session (net.session):
+      # its close does nothing, start / stop / run are the object layer's
+      # receiving thread (net.start / net.stop / net.run), and
+      # Asterism.close (or the end of the connect block) closes the session
+      # with everything declared on it.
+      def shared?
+        @shared
       end
 
       # opts: those of Session#put (attachment:, encoding:, priority:,
@@ -370,15 +388,23 @@ module Asterism
       def declare_keyexpr(key) = @session.declare_keyexpr(key)
 
       # Stops receiving and closes the session (with everything declared on
-      # it). Idempotent.
+      # it). Idempotent. On a shared? Connection (net.session) it does
+      # nothing: close what you declared on it (subscriptions, publishers,
+      # ROS nodes) one by one, or let Asterism.close close them.
       def close
+        if @shared
+          ::Asterism.warn_once(self, "asterism: net.session belongs to Asterism; its close is ignored " \
+                                     "(net.close closes it)")
+          return nil
+        end
         @runner.close
         @session.close
         nil
       end
 
       def inspect
-        "#<Asterism::Zenoh::Connection #{closed? ? 'closed' : zid}#{running? ? ' running' : ''}>"
+        "#<Asterism::Zenoh::Connection #{closed? ? 'closed' : zid}#{@shared ? ' shared' : ''}" \
+          "#{running? ? ' running' : ''}>"
       end
 
       private

data/lib/asterism/cruby.rb

@@ -24,6 +24,44 @@ module Asterism
     Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
   end
 
+  # The profile's defaults on CRuby (mrblib/profile.rb): kind "cruby" and
+  # the icon bundled with the gem (replace it with Asterism.profile(icon:)).
+  ICON_FILE = File.expand_path("../../data/icon.png", __dir__)
+
+  def self.default_profile_kind
+    "cruby"
+  end
+
+  def self.default_icon_path
+    ICON_FILE
+  end
+
+  def self.read_icon_file(path)
+    File.binread(path)
+  rescue SystemCallError
+    nil
+  end
+
+  module Profile
+    # Icons come out of MessagePack as UTF-8 Strings: hand them out as the
+    # bytes they are.
+    class << self
+      alias_method :check_portable, :check
+
+      def check(h)
+        out = check_portable(h)
+        out["icon"] = out["icon"].b if out&.key?("icon")
+        out
+      end
+
+      alias_method :icon_portable!, :icon!
+
+      def icon!(v)
+        icon_portable!(v).b.freeze
+      end
+    end
+  end
+
   def self.error_reply(klass, message)
     ::MessagePack.pack(["error", klass.to_s, message.to_s], compatibility_mode: true)
   end

data/lib/asterism/version.rb

@@ -1,5 +1,6 @@
 module Asterism
-  # The gem's version (the CRuby gem asterism; it depends on asterism-zenoh
-  # of the same version).
-  VERSION = "0.4.1"
+  # The gem's version (the CRuby gem asterism). The Zenoh binding it needs
+  # is in asterism.gemspec (asterism-zenoh ~> 0.4.0 for 0.5.0 and 0.6.0:
+  # the bindings did not change; see CHANGELOG.md).
+  VERSION = "0.6.0"
 end

data/lib/asterism.rb

@@ -12,7 +12,7 @@ require "asterism/zenoh"
 require_relative "asterism/version"
 
 # The same order as an mrbgem's mrblib (alphabetical).
-%w[asterism cdr future proxy ros].each do |f|
+%w[asterism cdr future profile proxy ros].each do |f|
   require_relative "../mrblib/#{f}"
 end
 require_relative "asterism/cruby"

data/mrblib/asterism.rb

@@ -14,6 +14,7 @@
 #   asterism/<node>/<app>/<object>/meta   get: reply {"methods" => [[name, arity], ...]}
 #   asterism/<node>                       liveliness: the node is up
 #   asterism/<node>/<app>/<object>        liveliness: the object is exposed
+#   asterism/<node>/@profile              get: reply the node's profile (profile.rb)
 #
 # Everything is polled: nothing runs behind the application's back. A call
 # that waits for its answer keeps polling meanwhile and answers the calls
@@ -221,20 +222,26 @@ module Asterism
       @node_token = s.liveliness("#{ROOT}/#{node}")
       @queryable = s.queryable("#{ROOT}/#{node}/#{app}/**", depth: 32)
       @watch = s.liveliness_watch("#{ROOT}/**", depth: watch_depth)
+      @profile_queryable = s.queryable("#{ROOT}/#{node}/#{Profile::KEY}", depth: 4)
     rescue Asterism::Zenoh::Error => e
       s.close
       raise Disconnected, e.message
     end
+    s.extend(SharedSession) # Asterism.session: the application's close does not close it
     @session = s
     @node = node
     @app = app
     @objects = {}  # name => [object, {method name => arity}, token]
-    @alive = {}    # "node/app/object" => true (from liveliness)
+    @alive = {}    # "node/app/object" => node (from liveliness)
     @nodes = {}    # node => true (from liveliness)
     @proxies = {}
     @depth = 0
     @lost = nil
     @known = []    # the other nodes told to on_join so far
+    @known_set = {} # the same, as node => true
+    @node_list = [node] # what nodes returns (this node first), rebuilt on a change
+    @nodes_changed = false # liveliness changed since tell_nodes last compared
+    tell_profile   # for those who follow the profiles (the reply is the queryable's)
     self
   end
 
@@ -295,19 +302,67 @@ module Asterism
     @objects = {}
     @alive = {}
     @nodes = {}
+    @node_list = nil
+    @nodes_changed = true
     @proxies = {}
-    s.close if s
+    if s
+      @releasing = s
+      begin
+        s.close
+      ensure
+        @releasing = nil
+      end
+    end
     @node_token = nil
     @queryable = nil
     @watch = nil
+    @profile_queryable = nil
   end
 
-  # @api private
+  # The Zenoh session of the connection (an Asterism::Zenoh::Session), for
+  # what the object layer does not do: put and subscribe, a ROS 2 node
+  # (Asterism::ROS::Node.new(Asterism.session, ...)), anything of the
+  # Zenoh API. One connection for everything: on a router that lets each
+  # pass in once, a second session would not get in, and a ROS 2 node on
+  # this session is part of this node (the same Zenoh ID).
+  #
+  # The session stays Asterism's: its close does nothing (it warns once);
+  # Asterism.close closes it, and with it everything declared on it (the
+  # application's subscribers, publishers, ROS 2 nodes). After a lost
+  # connection and a new Asterism.connect, take Asterism.session again and
+  # declare those again. Polling it (session.poll, node.poll) is fine:
+  # Asterism.poll polls it too, each entity keeps what came for it.
+  # Raises Disconnected when not connected (as the calls do).
+  def self.session
+    raise Disconnected, (@lost || "not connected") unless connected?
+    @session
+  end
+
+  # @api private (the name before 0.6.0; Asterism.session is the same)
   def self.session!
     raise Disconnected, (@lost || "not connected") unless @session
     @session
   end
 
+  # Whether Asterism itself is closing s (SharedSession#close).
+  # @api private
+  def self.releasing?(s)
+    !@releasing.nil? && @releasing.equal?(s)
+  end
+
+  # Extended onto the session of Asterism.connect: the session belongs to
+  # Asterism, so a close from anyone else (the application, a library that
+  # was handed Asterism.session) does nothing. Asterism.close and a lost
+  # connection close it.
+  module SharedSession
+    def close
+      return super if ::Asterism.releasing?(self)
+      ::Asterism.warn_once(self, "asterism: Asterism.session belongs to Asterism; its close is ignored " \
+                                 "(Asterism.close closes it)")
+      nil
+    end
+  end
+
   # The connection went away: closed, but the next Asterism.poll still tells
   # on_leave about every node known until then.
   # @api private
@@ -357,6 +412,10 @@ module Asterism
   # Call from the application's update loop. Answers the calls that came
   # in, follows who is alive and calls the on_join / on_leave blocks. false
   # once the connection is closed.
+  #
+  # Cheap when nothing came: each queue is looked at by its count first,
+  # and the list of nodes (and the comparison behind on_join / on_leave)
+  # is made again only after a liveliness change.
   def self.poll
     ok = @session ? pump : false
     tell_nodes
@@ -404,14 +463,43 @@ module Asterism
   def self.tell_nodes
     known = @known
     return if known.nil?
-    now = @session ? nodes : []
-    now.shift if @session # this node
+    # Nothing came on the liveliness watch since the last comparison (and
+    # the connection is neither new nor lost): nothing can have changed.
+    return unless @nodes_changed
+    @nodes_changed = false
+    now = []
+    now_set = {}
+    if @session
+      list = node_list
+      i = 1 # list[0] is this node
+      while i < list.size
+        n = list[i]
+        now << n
+        now_set[n] = true
+        i += 1
+      end
+    end
+    known_set = @known_set || {}
     joined = []
     left = []
-    now.each { |n| joined << n unless known.include?(n) }
-    known.each { |n| left << n unless now.include?(n) }
+    i = 0
+    while i < now.size
+      joined << now[i] unless known_set[now[i]]
+      i += 1
+    end
+    i = 0
+    while i < known.size
+      left << known[i] unless now_set[known[i]]
+      i += 1
+    end
     # After a loss, everything has been told: nothing more to compare.
-    @known = @session ? now : nil
+    if @session
+      @known = now
+      @known_set = now_set
+    else
+      @known = nil
+      @known_set = nil
+    end
     tell_each("on_join", @on_join, joined)
     tell_each("on_leave", @on_leave, left)
   end
@@ -447,6 +535,7 @@ module Asterism
       return false
     end
     answer_calls
+    answer_profile
     follow_liveliness
     !@session.nil?
   rescue Asterism::Zenoh::Error => e
@@ -488,9 +577,10 @@ module Asterism
   # @api private
   def self.follow_liveliness
     w = @watch
-    return unless w
+    return unless w && w.pending > 0
     # Array forms instead of blocks called from C (see Future#collect).
     events = w.each_pending
+    @nodes_changed = true if events.size > 0
     if events.size > 0 && w.dropped > 0
       warn_once(w, "asterism: #{w.dropped} liveliness changes dropped (more than #{watch_depth} at once); " \
                    "Asterism.each and Asterism.nodes may miss some objects")
@@ -510,24 +600,49 @@ module Asterism
         end
       elsif parts.size == 3
         if alive
-          @alive[rest] = true
+          @alive[rest] = parts[0]
         else
           @alive.delete(rest)
         end
       end
     end
+    @node_list = nil
   end
 
   # The node IDs alive now, this one first.
   def self.nodes
     return [] unless @session
+    node_list.dup
+  end
+
+  # The list behind nodes, made again only after a liveliness change (the
+  # caller must not change it). @api private
+  def self.node_list
+    list = @node_list
+    return list if list
     list = [@node]
-    @nodes.each_key { |n| list << n unless list.include?(n) }
-    @alive.each_key do |path|
-      n = path.split("/")[0]
-      list << n unless list.include?(n)
+    seen = { @node => true }
+    names = @nodes.keys
+    i = 0
+    while i < names.size
+      n = names[i]
+      unless seen[n]
+        seen[n] = true
+        list << n
+      end
+      i += 1
     end
-    list
+    owners = @alive.values
+    i = 0
+    while i < owners.size
+      n = owners[i]
+      unless seen[n]
+        seen[n] = true
+        list << n
+      end
+      i += 1
+    end
+    @node_list = list
   end
 
   # The exposed objects alive now whose <node>/<app>/<object> matches the
@@ -538,11 +653,15 @@ module Asterism
   def self.each(pattern = "**")
     paths = []
     if @session
+      seen = {}
       @objects.each_key do |name|
         path = "#{@node}/#{@app}/#{name}"
-        paths << path if glob?(pattern, path)
+        if glob?(pattern, path)
+          paths << path
+          seen[path] = true
+        end
       end
-      @alive.each_key { |path| paths << path if glob?(pattern, path) && !paths.include?(path) }
+      @alive.each_key { |path| paths << path if !seen[path] && glob?(pattern, path) }
     end
     proxies = paths.map { |path| self[path] }
     return proxies unless block_given?
@@ -614,7 +733,7 @@ module Asterism
   # @api private
   def self.answer_calls
     qa = @queryable
-    return unless qa
+    return unless qa && qa.pending > 0
     # Without a block, so that a handler that waits (and so polls) does not
     # re-enter the queryable's iteration.
     queries = qa.each_pending

data/mrblib/profile.rb

@@ -0,0 +1,362 @@
+# A node's profile: what it runs on, where, a display name and an icon,
+# told by the node itself (0.5.0).
+#
+#   Asterism.profile(name: "Rover", icon: png)   # this node's; returns it
+#   Asterism.profile                             # => {"kind" => "picoruby", "name" => "Rover", ...}
+#   Asterism.profile_of("fmruby-aaaaaa")         # another node's, or nil
+#
+# Key: asterism/<node>/@profile (a queryable of every application connected
+# as that node). The reply is a MessagePack Hash:
+#   "kind"       what Ruby runs the node: "family_mruby", "picoruby",
+#                "cruby", "console" (others are allowed)
+#   "host"       where it runs, optional ("atoms3r", "tab5", "sim", ...)
+#   "name"       a display name, optional
+#   "icon"       PNG bytes, optional (8 KB and 256x256 at most)
+#   "icon_hash"  the icon's summary (Profile.png_info): a reader that has
+#                that icon already asks again with the parameter icon=0 and
+#                gets the rest without it
+# Each connect, and each change while connected, also puts the profile
+# without its icon on the same key, for those who follow it (a console).
+#
+# Room left for later: an application's own profile would be
+# asterism/<node>/<app>/@profile, with the same Hash.
+module Asterism
+  module Profile
+    # The kinds this version knows. Others pass: a kind is any lower-case
+    # word (a-z, 0-9, _; up to KIND_MAX bytes) starting with a letter.
+    KINDS = ["family_mruby", "picoruby", "cruby", "console"]
+    KEY = "@profile"
+    ICON_MAX = 8192      # bytes
+    ICON_SIDE_MAX = 256  # pixels, each side
+    KIND_MAX = 32
+    HOST_MAX = 32
+    NAME_MAX = 64
+    PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10]
+
+    # [width, height, icon_hash] of a PNG that a profile may carry, or nil.
+    # Checks the signature, the size (ICON_MAX bytes), that the chunks tile
+    # the bytes from IHDR to IEND, and the image's sides (ICON_SIDE_MAX).
+    #
+    # icon_hash is the Adler-32 (8 hex digits) of the chunks' CRC-32 fields,
+    # in order: each CRC already sums up its chunk, so the summary costs a
+    # few bytes of arithmetic instead of a pass over the whole file (small
+    # integers only, the same on every Ruby). On CRuby it equals
+    # Zlib.adler32 of those fields joined.
+    def self.png_info(b)
+      return nil unless b.is_a?(String)
+      size = b.bytesize
+      return nil if size < 8 + 25 + 12 || size > ICON_MAX
+      i = 0
+      while i < 8
+        return nil unless b.getbyte(i) == PNG_SIGNATURE[i]
+        i += 1
+      end
+      pos = 8
+      first = true
+      w = 0
+      h = 0
+      a = 1
+      s = 0
+      while pos + 12 <= size
+        # The length is 4 bytes; anything past 16 bits is larger than ICON_MAX.
+        return nil unless b.getbyte(pos) == 0 && b.getbyte(pos + 1) == 0
+        len = b.getbyte(pos + 2) * 256 + b.getbyte(pos + 3)
+        nxt = pos + 12 + len
+        return nil if nxt > size
+        if first
+          return nil unless type?(b, pos, 73, 72, 68, 82) && len == 13 # IHDR
+          return nil unless b.getbyte(pos + 8) == 0 && b.getbyte(pos + 9) == 0
+          return nil unless b.getbyte(pos + 12) == 0 && b.getbyte(pos + 13) == 0
+          w = b.getbyte(pos + 10) * 256 + b.getbyte(pos + 11)
+          h = b.getbyte(pos + 14) * 256 + b.getbyte(pos + 15)
+          return nil if w < 1 || h < 1 || w > ICON_SIDE_MAX || h > ICON_SIDE_MAX
+          first = false
+        end
+        k = nxt - 4
+        while k < nxt
+          a = (a + b.getbyte(k)) % 65521
+          s = (s + a) % 65521
+          k += 1
+        end
+        if type?(b, pos, 73, 69, 78, 68) # IEND
+          return nil unless nxt == size
+          return [w, h, hex4(s) + hex4(a)]
+        end
+        pos = nxt
+      end
+      nil
+    end
+
+    # @api private
+    def self.type?(b, pos, c0, c1, c2, c3)
+      b.getbyte(pos + 4) == c0 && b.getbyte(pos + 5) == c1 && b.getbyte(pos + 6) == c2 && b.getbyte(pos + 7) == c3
+    end
+
+    # @api private
+    def self.hex4(n)
+      t = n.to_s(16)
+      t = "0" + t while t.length < 4
+      t
+    end
+
+    # A received profile, cleaned: the known fields that pass their checks
+    # (a field that does not is left out; an icon that is not a valid PNG
+    # goes with its hash). nil when it is not a profile (no valid kind).
+    def self.check(h)
+      return nil unless h.is_a?(Hash)
+      kind = h["kind"]
+      return nil unless kind.is_a?(String) && kind?(kind)
+      out = { "kind" => kind }
+      host = h["host"]
+      out["host"] = host if host.is_a?(String) && !host.empty? && host.bytesize <= HOST_MAX
+      name = h["name"]
+      out["name"] = name if name.is_a?(String) && !name.empty? && name.bytesize <= NAME_MAX
+      icon = h["icon"]
+      if icon.is_a?(String)
+        info = png_info(icon)
+        if info
+          out["icon"] = icon
+          out["icon_hash"] = info[2]
+        end
+      elsif hash_text?(h["icon_hash"])
+        out["icon_hash"] = h["icon_hash"]
+      end
+      out
+    end
+
+    # @api private
+    def self.kind?(s)
+      n = s.bytesize
+      return false if n < 1 || n > KIND_MAX
+      i = 0
+      while i < n
+        c = s.getbyte(i)
+        lower = c >= 97 && c <= 122
+        return false unless lower || (i > 0 && ((c >= 48 && c <= 57) || c == 95))
+        i += 1
+      end
+      true
+    end
+
+    # @api private
+    def self.hash_text?(s)
+      return false unless s.is_a?(String) && s.bytesize == 8
+      i = 0
+      while i < 8
+        c = s.getbyte(i)
+        return false unless (c >= 48 && c <= 57) || (c >= 97 && c <= 102)
+        i += 1
+      end
+      true
+    end
+
+    # The checks of Asterism.profile (ArgumentError, with the reason).
+    # @api private
+    def self.kind!(v)
+      s = v.is_a?(Symbol) ? v.to_s : v
+      unless s.is_a?(String) && kind?(s)
+        raise ArgumentError, "profile kind: #{v.inspect} is not a lower-case word (a-z, 0-9, _; " \
+                             "#{KIND_MAX} bytes at most), e.g. :cruby"
+      end
+      s
+    end
+
+    # @api private
+    def self.text!(what, v, max)
+      s = v.is_a?(Symbol) ? v.to_s : v
+      raise ArgumentError, "profile #{what}: expected a String, got #{v.class}" unless s.is_a?(String)
+      raise ArgumentError, "profile #{what}: empty (pass nil to leave it out)" if s.empty?
+      raise ArgumentError, "profile #{what}: #{s.bytesize} bytes (#{max} at most)" if s.bytesize > max
+      s
+    end
+
+    # @api private
+    def self.icon!(v)
+      raise ArgumentError, "profile icon: expected the bytes of a PNG (a String), got #{v.class}" unless v.is_a?(String)
+      if v.bytesize > ICON_MAX
+        raise ArgumentError, "profile icon: #{v.bytesize} bytes (#{ICON_MAX} at most)"
+      end
+      unless png_info(v)
+        raise ArgumentError, "profile icon: not a PNG, or not one this accepts (up to " \
+                             "#{ICON_SIDE_MAX}x#{ICON_SIDE_MAX}, chunks from IHDR to IEND)"
+      end
+      v
+    end
+
+    # Whether a query's parameters ask for the icon (icon=0 says no).
+    # @api private
+    def self.wants_icon?(params)
+      return true if params.nil? || params.empty?
+      params.split(";").each do |pair|
+        kv = pair.split("=")
+        next unless kv[0] == "icon"
+        v = kv[1].to_s
+        return false if v == "0" || v == "no" || v == "false"
+      end
+      true
+    end
+  end
+
+  # This node's profile. With keywords, sets those fields and returns the
+  # profile; without, returns it. The fields: kind: (a Symbol or String;
+  # nil goes back to the default), name:, host: (Strings; nil leaves them
+  # out), icon: (the bytes of a PNG; nil for no icon). The fields not given
+  # stay as they are. Raises ArgumentError for a field it does not accept
+  # (see Asterism::Profile).
+  #
+  # The defaults: kind "picoruby" on mruby / PicoRuby, "cruby" on CRuby; no
+  # host, no name; the icon is the file at Asterism.default_icon_path when
+  # there is one (the boards: /usr/share/asterism/icon.png; CRuby: the gem's
+  # data/icon.png). A board's firmware may set its own defaults with this
+  # same call before the application runs (Family mruby does).
+  #
+  # Kept across connect and close (it belongs to the process, or the VM on
+  # a board). While connected, a change is also put on the profile's key.
+  def self.profile(**fields)
+    return profile_hash(true) if fields.empty?
+    changes = {}
+    fields.each do |k, v|
+      key = k.to_s
+      if key == "kind"
+        changes[key] = v.nil? ? nil : Profile.kind!(v)
+      elsif key == "name"
+        changes[key] = v.nil? ? nil : Profile.text!("name", v, Profile::NAME_MAX)
+      elsif key == "host"
+        changes[key] = v.nil? ? nil : Profile.text!("host", v, Profile::HOST_MAX)
+      elsif key == "icon"
+        changes[key] = v.nil? ? nil : Profile.icon!(v)
+      else
+        raise ArgumentError, "unknown profile field #{key} (kind, name, host, icon)"
+      end
+    end
+    set = (@profile_set ||= {})
+    changes.each do |k, v|
+      if v.nil? && k != "icon"
+        set.delete(k)
+      else
+        set[k] = v # icon: nil stays, so the default file is not used
+      end
+    end
+    @profile_icon = nil if changes.key?("icon")
+    tell_profile
+    profile_hash(true)
+  end
+
+  # Another node's profile (Asterism::Profile.check has cleaned it), or nil
+  # when it does not answer in time (an older version of Asterism, a ROS 2
+  # node, a node that is gone). icon: false asks for it without the icon
+  # bytes (icon_hash still says which icon it is). timeout: in seconds (or
+  # timeout_ms:), 2.0 by default. Waits like a call (polling, answering
+  # calls meanwhile); raises Disconnected when not connected. This node's
+  # own profile comes without the network.
+  def self.profile_of(node, icon: true, timeout: nil, timeout_ms: nil)
+    f = profile_async(node, icon, timeout, timeout_ms)
+    begin
+      raw = f.raw_value
+    rescue Disconnected
+      raise
+    rescue Error
+      return nil # no answer in time, or not MessagePack
+    end
+    Profile.check(raw)
+  end
+
+  # @api private
+  def self.profile_async(node, icon, timeout, timeout_ms)
+    node = check_name("node", node)
+    ms = time_ms("Asterism.profile_of", timeout, timeout_ms, nil, DEFAULT_TIMEOUT_MS)
+    path = "#{node}/#{Profile::KEY}"
+    return Future.answered(path, "profile", Codec.pack(profile_hash(icon))) if @session && node == @node
+    begin
+      g = session!.get("#{ROOT}/#{path}", timeout_ms: ms, params: icon ? nil : "icon=0")
+    rescue Asterism::Zenoh::Error => e
+      lost(e.message)
+      raise Disconnected, e.message
+    end
+    Future.new(path, "profile", g, now_ms + ms, ms)
+  end
+
+  # The kind when the application did not set one.
+  # @api private
+  def self.default_profile_kind
+    "picoruby"
+  end
+
+  # Where the default icon is read from (when the application gave none);
+  # nil for none. CRuby: the gem's data/icon.png.
+  def self.default_icon_path
+    "/usr/share/asterism/icon.png"
+  end
+
+  # The bytes of a file, nil when it cannot be read.
+  # @api private
+  def self.read_icon_file(path)
+    return nil unless Object.const_defined?(:File) && File.exist?(path)
+    File.open(path, "r") { |f| f.read }
+  rescue
+    nil
+  end
+
+  # The profile as sent: String keys, the icon only when with_icon.
+  # @api private
+  def self.profile_hash(with_icon)
+    set = @profile_set || {}
+    h = { "kind" => set["kind"] || default_profile_kind }
+    h["host"] = set["host"] if set["host"]
+    h["name"] = set["name"] if set["name"]
+    icon = profile_icon
+    if icon
+      h["icon"] = icon[0] if with_icon
+      h["icon_hash"] = icon[1]
+    end
+    h
+  end
+
+  # [bytes, icon_hash] of this node's icon, or nil. The default file is
+  # read once, when the profile is first needed.
+  # @api private
+  def self.profile_icon
+    if @profile_icon.nil?
+      set = @profile_set || {}
+      bytes = set.key?("icon") ? set["icon"] : nil
+      unless set.key?("icon")
+        path = default_icon_path
+        bytes = path ? read_icon_file(path) : nil
+      end
+      info = bytes ? Profile.png_info(bytes) : nil
+      @profile_icon = info ? [bytes, info[2]] : false
+    end
+    @profile_icon ? @profile_icon : nil
+  end
+
+  # Puts the profile without its icon on its key (while connected).
+  # @api private
+  def self.tell_profile
+    s = @session
+    return unless s
+    s.put("#{ROOT}/#{@node}/#{Profile::KEY}", Codec.pack(profile_hash(false)))
+  rescue Asterism::Zenoh::Error
+    nil # the next poll notices a lost connection
+  end
+
+  # @api private
+  def self.answer_profile
+    qa = @profile_queryable
+    return unless qa && qa.pending > 0
+    queries = qa.each_pending
+    i = 0
+    while i < queries.size
+      q = queries[i]
+      i += 1
+      begin
+        q.reply("#{ROOT}/#{@node}/#{Profile::KEY}", Codec.pack(profile_hash(Profile.wants_icon?(q.params))))
+      ensure
+        begin
+          q.finish
+        rescue Asterism::Zenoh::Error
+          # the session went away meanwhile
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asterism
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asterism-zenoh
@@ -50,6 +50,7 @@ files:
 - LICENSE
 - NOTICE
 - README.md
+- data/icon.png
 - data/msgs/LICENSE-Apache-2.0.txt
 - data/msgs/LICENSE-BSD-3-Clause-tf2_msgs.txt
 - data/msgs/NOTICE
@@ -147,6 +148,7 @@ files:
 - mrblib/asterism.rb
 - mrblib/cdr.rb
 - mrblib/future.rb
+- mrblib/profile.rb
 - mrblib/proxy.rb
 - mrblib/ros.rb
 - tools/asterism_msggen.rb