asterism 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd2f9fe700f5ca0b88f98fc6598217c87be3257e31a655d33ba710f9260b76ea
-  data.tar.gz: '0943fd816e28b2a60c5d812095d5c87d9ac0f1a8d1a0aaf7428989f34526aeb5'
+  metadata.gz: b55c825f8859d86ba09baad0585c0f416a168023b8032c3f871d63bebef0538c
+  data.tar.gz: 4d6fd26b326e62348e4fba8c6881c48b5b7145dd0b0c701eb7ba1dcc1bf5b261
 SHA512:
-  metadata.gz: 86426bc1893654601c5a7b9234b09d82b10c6e8260553160f2484b2665ec0eba6bf4293fa1994f88b814997cbad2c69af2d4b2a492f034303ee20c61145f3f43
-  data.tar.gz: 387f4b1de6234f98b3c4b71ce0aee0d6f4d70ec32250350786cff73ec4cf1d500a64277b90f389f2544465409279aba601ac67fd0b3470919f0902727a21334e
+  metadata.gz: 0acc8e1c4e4f028124d247a54e35ebda3451449dcfc46da503d345c857502200b1b68b4f15a4d59fbb7a603d9331f6996aa9072b1426e039fea87b43efbddd5e
+  data.tar.gz: 03b912800f24b881a7e01eb6479c2d8c3c2c32a3346538ea60ae5f65c431f3035e097f5fc90fdcaec7734efbf95496544c4b0dd174b12e6be20cabfec2db3635

data/CHANGELOG.md

@@ -6,6 +6,41 @@ 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.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_api_*.rb` (the CRuby API) |
+| `host_test/` | `rake test:mruby`: the shared layer on mruby (profiles between two mruby processes) |
+| `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,9 @@ 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).
 
 ## Which API?
 
@@ -83,7 +87,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.5.0.gem
 ```
 
 From the working trees, without installing:
@@ -111,8 +115,17 @@ 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`)
 ```
 
+`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 +144,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 +251,7 @@ 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.nodes`, `node_id`, `app`, `connected?`, `lost_reason`, `poll`, `close` | |
 
 ### Over TLS (a router on the internet)
@@ -400,6 +425,60 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 | `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. |
+| `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.
 
 ## Errors
 
@@ -441,6 +520,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
@@ -530,8 +610,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.5.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 +683,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].each do |m|
       define_method(m) do |*args, **kw, &blk|
         ::Asterism::LOCK.synchronize { super(*args, **kw, &blk) }
       end
@@ -147,6 +148,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.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: the bindings
+  # did not change; see CHANGELOG.md).
+  VERSION = "0.5.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,6 +222,7 @@ 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
@@ -235,6 +237,7 @@ module Asterism
     @depth = 0
     @lost = nil
     @known = []    # the other nodes told to on_join so far
+    tell_profile   # for those who follow the profiles (the reply is the queryable's)
     self
   end
 
@@ -300,6 +303,7 @@ module Asterism
     @node_token = nil
     @queryable = nil
     @watch = nil
+    @profile_queryable = nil
   end
 
   # @api private
@@ -447,6 +451,7 @@ module Asterism
       return false
     end
     answer_calls
+    answer_profile
     follow_liveliness
     !@session.nil?
   rescue Asterism::Zenoh::Error => e

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
+    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.5.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