asterism 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +110 -0
  3. data/README.md +245 -63
  4. data/lib/asterism/cruby/objects.rb +25 -10
  5. data/lib/asterism/cruby/ros.rb +6 -4
  6. data/lib/asterism/cruby/zenoh.rb +190 -60
  7. data/lib/asterism/version.rb +1 -1
  8. data/lib/asterism.rb +2 -2
  9. data/mrblib/asterism.rb +112 -19
  10. data/mrblib/cdr.rb +5 -1
  11. data/mrblib/future.rb +11 -2
  12. data/mrblib/proxy.rb +13 -3
  13. data/mrblib/ros.rb +118 -38
  14. metadata +5 -4
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f03c6be1c5461da008a067c55b609a009b31b7552810836b7272bcdd35443ba7
4
- data.tar.gz: df8c8641c8039408dcb3ca803b7fdcfe0a24e3eef3199da0b1277e980977f936
3
+ metadata.gz: 1100d56c90f65bbfdf0d6fcd5c383483e61bbb815ced349307e67226b07ebcdb
4
+ data.tar.gz: 6adef73606920ab9e432b9bddf430038924181d77bdaa5d2fb60e424882204d7
5
5
  SHA512:
6
- metadata.gz: 663fbb3e79d9b824128b541b899028809d899916af70a28fe761581fa2e28285f9841ef78dfafd088c2583f2c9df705328566b1f465ec31886df277c013c90a2
7
- data.tar.gz: d447307b7bba1387d35316044c483f974a814ab1b0a4c7f5d32e17e8fc0b954ed2388ee53aaef9bf780bb7ccb98a93669fdf30f0efb7357d007535cae26a33ec
6
+ metadata.gz: 2bc05b237dc8cd2fc04b169c132263004718ef8c5fe04f7037bf8ec415ae72e3da57e962d77ccd93b224f5875187004c511e13b25145f496e3c85f5ef0006135
7
+ data.tar.gz: c12becb195ae73c664bb31e274865ff738c2074d42ffc0381312ccf32b73c883c9ec0605079b5c867272c47246116e37b65ca51db7a8e2b5c287ba020032b70a
data/CHANGELOG.md ADDED
@@ -0,0 +1,110 @@
1
+ # Changelog
2
+
3
+ All notable changes to asterism (the CRuby gem) and picoruby-asterism (the
4
+ mrbgem; the same `mrblib/`). Nothing has been published to rubygems.org
5
+ yet; the versions below are the ones in this repository. From 0.4.0 the
6
+ two Zenoh bindings (asterism-zenoh, picoruby-asterism-zenoh) carry the
7
+ same version number.
8
+
9
+ ## 0.4.0
10
+
11
+ The first step of the API review toward 1.0 (docs/api_review.md):
12
+ additions, deprecations and fixes. Every 0.3.0 call works as before.
13
+ Needs asterism-zenoh / picoruby-asterism-zenoh 0.4.0.
14
+
15
+ Added
16
+
17
+ - Time limits in seconds everywhere: `Asterism[path, timeout: 2.0]` (or
18
+ `timeout_ms:`), `client.call` / `node.call(timeout:)`,
19
+ `Asterism.connect(connect_timeout:, check_timeout:)`; on the CRuby API
20
+ `timeout_ms:` next to `timeout:` and `query_timeout:` on
21
+ `advanced_subscriber`. Giving a time limit twice raises `ArgumentError`.
22
+ Time-out messages give both units (`within 2.0 s (2000 ms)`).
23
+ - `node.every(ms: 500)`, `Timer#period_ms`.
24
+ - `Future#took`, `ROS::Call#took` (seconds).
25
+ - `request:` on `client.call` / `call_async` / `node.call`.
26
+ - `node.subscribe(topic, type)` without a block returns the subscription
27
+ (as `node.subscription`) instead of raising, on the boards as on CRuby.
28
+ - `pending` / `received` on `ROS::Subscription`.
29
+ - `Proxy#remote_methods`.
30
+ - `Asterism.off_join` / `off_leave` (and on `Net`).
31
+ - One error tree under `Asterism::Error`: `TimeoutError` (was `Timeout`),
32
+ `ROS::TimeoutError` (under `TimeoutError`; was `ROS::Timeout`),
33
+ `ROS::UnknownType` and `CDR::DecodeError` moved under it, and the
34
+ bindings' `Zenoh::Error` / `Zenoh::ClosedError` are under it too. The ROS
35
+ layer raises `Zenoh::ClosedError` when its session or entity is closed.
36
+ - CRuby API: `Connection#connection_count`, `Subscription#each_sample`,
37
+ `c.liveliness(key) { }` and `c.publisher(key) { |pub| }` (closed after
38
+ the block), `net[path, timeout_ms:]`.
39
+ - `DEFAULT_TIMEOUT`, `CHECK_TIMEOUT`, `Client::DEFAULT_TIMEOUT` (seconds).
40
+ - CRuby API: `depth:` on `Connection#get`, `#liveliness_get` and
41
+ `Querier#get`. A get's queue held 16 and could not be changed, so a
42
+ wildcard get past the 16th reply lost the rest (a router answers in one
43
+ burst; `liveliness_get("@ros2_lv/**")` returned 16 of 31).
44
+ - CRuby API: `dropped` (with `received`, and `errors` for gets) on what a
45
+ get gives: `liveliness_get` returns a `KeyList` (an Array with
46
+ `dropped` / `received`), `get` and `Querier#get` without a block a
47
+ `GetEnumerator` (an Enumerator with the counts of the last get it sent).
48
+ `Watch#dropped` / `pending` / `received` (before only through
49
+ `w.watch.dropped`).
50
+ - CRuby API: a get, liveliness watch or subscription whose depth was left
51
+ at the default warns once (`Asterism.warn_once`) when something was
52
+ dropped. So does the object layer's watch, on every Ruby.
53
+ - README: "Which API?" (the portable API and the CRuby API), the error
54
+ tree, the defaults, the threads table, the deprecations and what 1.0
55
+ changes, reserved keywords. Internal methods are marked `@api private`.
56
+
57
+ Changed
58
+
59
+ - CRuby API: the default depth of `get`, `liveliness_get`, `Querier#get`
60
+ and `liveliness_watch` is the binding's `DEFAULT_GET_DEPTH` /
61
+ `DEFAULT_WATCH_DEPTH`, 1024 (was 16; the boards stay at 16).
62
+ - The object layer's liveliness watch (behind `Asterism.each` and
63
+ `Asterism.nodes`) holds 1024 on CRuby (64 on the boards, as before).
64
+
65
+ Deprecated (each warns once per name; `Asterism.deprecations = :raise`
66
+ raises instead)
67
+
68
+ - `Asterism[path, ms]` (the time as a positional argument; a Float there
69
+ warns with its own message: it is milliseconds).
70
+ - `Asterism::Timeout`, `Asterism::ROS::Timeout` (the names; they still
71
+ rescue the same errors, through `const_missing`, so that inside
72
+ `module Asterism` the name `Timeout` is Ruby's again).
73
+ - `Proxy#methods` returning the remote methods: `remote_methods`.
74
+ - CRuby API: `Connection#peers` (`connection_count`) and
75
+ `Connection::Subscription#each_pending` (`each_sample`).
76
+ - A request field named `timeout` / `timeout_ms` given as a keyword to
77
+ `client.call` (use `request:`).
78
+
79
+ Fixed
80
+
81
+ - A Float as the positional time limit was taken as milliseconds and
82
+ truncated (`Asterism[path, 2.0]` waited 2 ms); it now warns and says so.
83
+ - A service whose request has a field named like the time-limit keyword
84
+ could not be called with keyword fields: `request:` (or a Hash) now
85
+ carries the request, and `timeout:` the time limit.
86
+
87
+ ## 0.3.0
88
+
89
+ - CRuby API: publishers, queriers, the advanced publisher / subscriber and
90
+ events with blocks; `Asterism.connect(config:)` for TLS.
91
+ - Strings are built from a fresh String (frozen literals); CI on Ruby 3.2
92
+ to 4.0 and with frozen literals, against asterism-zenoh main, and an
93
+ installed-gem check.
94
+ - docs/api_review.md (the review this version starts on) and profile/
95
+ (the Ruby profile of the shared layer across implementations).
96
+
97
+ ## 0.2.0
98
+
99
+ - The CRuby API: blocks, a receiving thread and Enumerators over the
100
+ portable API (`Asterism::Zenoh.open`, `Asterism.connect { |net| }`,
101
+ `Asterism::ROS.connect`).
102
+ - In the shared layer: `on_join` / `on_leave`, `node.every`,
103
+ `node.subscribe` blocks and `deconstruct_keys`.
104
+
105
+ ## 0.1.0
106
+
107
+ - The pure Ruby layers as one source for the CRuby gem and the mrbgem: the
108
+ object layer (`Asterism.connect / expose / [] / poll`), `Asterism::CDR`,
109
+ `Asterism::ROS` (topics and services over rmw_zenoh's wire format), the
110
+ type generator and the bundled ROS 2 Jazzy types.
data/README.md CHANGED
@@ -9,11 +9,11 @@ repository holds the pure Ruby layers, written once for every Ruby:
9
9
  |---|---|
10
10
  | `mrblib/` | The layers: remote objects (`Asterism`), `Asterism::CDR`, `Asterism::ROS`. The source of truth for both forms below |
11
11
  | `mrbgem.rake` | The mrbgem `picoruby-asterism` (mruby / PicoRuby): compiles `mrblib/` |
12
- | `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 Ruby-like API (CRuby only) |
12
+ | `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) |
13
13
  | `data/msgs/` | ROS 2 message types generated from ROS 2 Jazzy's definitions (Apache-2.0, see NOTICE) |
14
14
  | `tools/` | The type generator `asterism_msggen.rb`, the Jazzy definitions it reads, `ros2_types.rb` (refreshes them from a ROS 2 image) |
15
- | `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_api_*.rb` (the Ruby-like API) |
16
- | `examples/` | CRuby: `node.rb` (objects with a board), `node_polled.rb` (the same with the polled API of the boards), `ros2_talker.rb` (topics, a timer, services with ROS 2), `zenoh.rb` (plain Zenoh) |
15
+ | `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_api_*.rb` (the CRuby API) |
16
+ | `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) |
17
17
 
18
18
  The Zenoh binding underneath is a separate gem with the same Ruby API on
19
19
  each Ruby:
@@ -31,15 +31,46 @@ in asterism-zenoh's
31
31
  The ones added in 0.3.0 are CRuby only: the shared layer (`mrblib/`) does
32
32
  not use them.
33
33
 
34
- Neither gem is on rubygems.org yet (version 0.3.0 builds from these
35
- repositories with `rake gem`).
34
+ Both gems are on rubygems.org (`gem install asterism` installs
35
+ asterism-zenoh too). What changed in each version is in
36
+ [CHANGELOG.md](CHANGELOG.md); 0.4.0 is the first step toward 1.0
37
+ ([docs/api_review.md](docs/api_review.md)) and only adds and deprecates
38
+ (see [Deprecations and 1.0](#deprecations-and-10)).
39
+
40
+ ## Which API?
41
+
42
+ Asterism has two APIs over the same layers. Both are in the CRuby gem;
43
+ the boards have the first one only.
44
+
45
+ | You write for | Use | Why |
46
+ |---|---|---|
47
+ | A board, or code that must run on both | the **portable API** ([below](#the-portable-api): `Asterism.poll`, `node.poll`, `each_pending`) | the only one on the boards; nothing runs behind your back |
48
+ | CRuby only (tools, servers, scripts) | the **CRuby API** ([The CRuby API](#the-cruby-api): `Asterism.connect { }`, `Asterism::Zenoh.open { }`, `Asterism::ROS.connect { }`) | blocks, a receiving thread, Enumerators, `Data` values |
49
+ | CRuby, but you own the loop (a game loop, a test) | the portable API | same as the boards |
50
+
51
+ Entry points and what they give:
52
+
53
+ | Call | Gives | Underneath |
54
+ |---|---|---|
55
+ | `Asterism::Zenoh::Session.open` | a `Session` (portable) | zenoh-c / zenoh-pico |
56
+ | `Asterism::Zenoh.open` | a `Zenoh::Connection` (CRuby) | `c.session` is the `Session` |
57
+ | `Asterism.connect` | `Asterism` itself (portable; one connection per process or VM), or a `Net` to the block (CRuby) | a `Session` of its own |
58
+ | `Asterism::ROS::Node.new(session, ...)` | a `Node` (portable) | the `Session` given |
59
+ | `Asterism::ROS.connect` | a `ROS::Connection` (CRuby) | `ros.zenoh` is the `Zenoh::Connection` |
60
+
61
+ Units: a time with no unit in its name is seconds (`timeout:`,
62
+ `connect_timeout:`, `check_timeout:`, `node.every(0.5)`, `DEFAULT_TIMEOUT`);
63
+ anything else says its unit (`timeout_ms:`, `every(ms: 500)`, `took_ms`,
64
+ `DEFAULT_TIMEOUT_MS`, `stamp_ns`). Both units are accepted everywhere a
65
+ time is taken, on both APIs and every Ruby; giving one twice raises
66
+ `ArgumentError`.
36
67
 
37
68
  ## Using it
38
69
 
39
70
  CRuby (needs CRuby 3.2+ and a C compiler):
40
71
 
41
72
  ```
42
- gem install asterism # also installs asterism-zenoh (~> 0.3.0) and msgpack
73
+ gem install asterism # also installs asterism-zenoh (~> 0.4.0) and msgpack
43
74
  ruby -e 'require "asterism"'
44
75
  ```
45
76
 
@@ -52,7 +83,7 @@ build but not yet tested. To install from the repositories instead:
52
83
 
53
84
  ```
54
85
  (cd ../asterism-zenoh && rake gem) && rake gem
55
- gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.3.0.gem pkg/asterism-0.3.0.gem
86
+ gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.0.gem pkg/asterism-0.4.0.gem
56
87
  ```
57
88
 
58
89
  From the working trees, without installing:
@@ -78,13 +109,15 @@ these repositories.
78
109
  rake # every suite
79
110
  rake test:msgs # generator, type hashes, CDR, bundled types (CRuby only; no Zenoh, no docker)
80
111
  rake test:objects # objects and Asterism::ROS between CRuby sessions over a local peer link
81
- rake test:api # the Ruby-like API (blocks, receiving threads, Enumerators)
112
+ rake test:api # the CRuby API (blocks, receiving threads, Enumerators)
82
113
  ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects test:api # the same through a zenohd router
83
114
  ```
84
115
 
85
116
  `test:objects` and `test:api` need asterism-zenoh: built next to this repository
86
117
  (`../asterism-zenoh`, its `rake compile`), or `ASTERISM_ZENOH_DIR`, or the
87
- installed gem.
118
+ installed gem. The tests run with deprecated calls raising
119
+ (`Asterism.deprecations = :raise`); the tests of the old forms switch it
120
+ back around themselves.
88
121
 
89
122
  ## Examples
90
123
 
@@ -102,11 +135,11 @@ ruby examples/ros2_talker.rb --router tcp/192.0.2.2:7447 [--service NAME]
102
135
  ruby examples/zenoh.rb --router tcp/192.0.2.2:7447 --name pc1
103
136
  ```
104
137
 
105
- ## The Ruby-like API (CRuby only)
138
+ ## The CRuby API
106
139
 
107
140
  On CRuby, `require "asterism"` also brings a layer with blocks, a receiving
108
141
  thread, Enumerators and pattern matching (`lib/asterism/cruby/`). It is
109
- built on the polled API below, which stays as it is: code written for a
142
+ built on the portable API below, which stays as it is: code written for a
110
143
  board still runs unchanged on CRuby, and code using this layer does not run
111
144
  on a board.
112
145
 
@@ -124,7 +157,7 @@ Asterism::Zenoh.open("tcp/192.0.2.2:7447") do |s| # closed when the block ends
124
157
  s.run # receive on this thread until Ctrl-C
125
158
  end
126
159
 
127
- # asterism-zenoh 0.3.0 (CRuby only)
160
+ # asterism-zenoh 0.3.0 and later (CRuby only)
128
161
  Asterism::Zenoh.open("tls/192.0.2.2:7447",
129
162
  config: { "transport/link/tls/root_ca_certificate" => "ca.pem" }) do |s|
130
163
  pub = s.publisher("home/pc/temp", encoding: "text/plain", priority: :data_high)
@@ -144,33 +177,32 @@ end
144
177
 
145
178
  | Call | Notes |
146
179
  |---|---|
147
- | `Asterism::Zenoh.open(locator = nil, mode:, listen:, scouting:, timestamping:, config:, config_file:, interval: 0.002)` | `Session.open` wrapped in a `Connection`. With a block: yields it, closes it after (also on an exception), returns the block's value |
148
- | `Connection.new(session)` | wraps a session opened with the polled API |
180
+ | `Asterism::Zenoh.open(locator = nil, mode:, listen:, scouting:, timestamping:, config:, config_file:, connect_timeout:, interval: 0.002)` | `Session.open` wrapped in a `Connection`. With a block: yields it, closes it after (also on an exception), returns the block's value |
181
+ | `Connection.new(session)` | wraps a session opened with the portable API |
149
182
  | `s.put(key, payload, attachment: nil, **opts)` | a payload that is not a String is sent as `to_s`. opts: `encoding:`, `priority:`, `congestion_control:`, `express:`, `reliability:`, `timestamp:`, `allowed_destination:` (asterism-zenoh's `Session#put`) |
150
183
  | `s.delete(key, **opts)` | subscribers get a `Sample` of kind `:delete` |
151
- | `s.publisher(key, **opts)` | a `Publisher`: `put(payload, attachment:, encoding:, timestamp:)`, `delete`, `matching?`, `on_matching { \|listening\| }` (on the receiving thread), `close` |
184
+ | `s.publisher(key, **opts)` | a `Publisher`: `put(payload, attachment:, encoding:, timestamp:)`, `delete`, `matching?`, `on_matching { \|listening\| }` (on the receiving thread), `close`. With a block: yields it and closes it after |
152
185
  | `s.advanced_publisher(key, cache:, sample_miss_detection:, publisher_detection:, **opts)` | the same `Publisher`, keeping the last samples for late subscribers (ROS 2's transient local) |
153
- | `s.advanced_subscriber(key, depth: 16, history:, recovery:, **opts) { \|sample\| }` | a `Subscription` that also gets the publishers' history; `on_publisher { \|key, alive\| }`, `on_miss { \|miss\| }` |
154
- | `s.querier(key, timeout: 2.0, **opts)` | a `Querier`: `get(params:, payload:, attachment:, encoding:, errors: false)` like `s.get`, `matching?`, `on_matching`, `close` |
186
+ | `s.advanced_subscriber(key, depth: 16, history:, recovery:, query_timeout:, **opts) { \|sample\| }` | a `Subscription` that also gets the publishers' history; `on_publisher { \|key, alive\| }`, `on_miss { \|miss\| }` |
187
+ | `s.querier(key, timeout: 2.0, **opts)` (or `timeout_ms:`) | a `Querier`: `get(params:, payload:, attachment:, encoding:, errors: false)` like `s.get`, `matching?`, `on_matching`, `close` |
155
188
  | `s.on_transport(history: false) { \|ev\| }` / `s.on_link { \|ev\| }` | a `TransportEvent` / `LinkEvent` (`added?` / `removed?`, `zid`, ...) on the receiving thread; returns an `Events` (`close`) |
156
189
  | `s.peer_zids`, `router_zids`, `transports`, `links`, `new_timestamp`, `declare_keyexpr(key)` | as in asterism-zenoh |
157
190
  | `s.subscribe(key, depth: 16) { \|sample\| }` | the block gets each `Sample` on the receiving thread. Returns a `Subscription` (`close` ends it) |
158
- | `s.subscribe(key, depth: 16)` | a `Subscription` to take from: `each(timeout: nil)` waits for samples (an Enumerator without a block; Enumerable), `each_pending` gives what is there now as Samples, `pending` / `received` / `dropped` / `closed?` / `close` |
191
+ | `s.subscribe(key, depth: 16)` | a `Subscription` to take from: `each(timeout: nil)` waits for samples (an Enumerator without a block; Enumerable), `each_sample` gives what is there now as Samples (`each_pending`, its old name here, is deprecated: in the portable API `each_pending` gives Arrays), `pending` / `received` / `dropped` / `closed?` / `close` |
159
192
  | `s.queryable(key, depth: 16, complete: false) { \|q\| }` | each query on the receiving thread, finished when the block returns. `q.reply(payload)` answers on the queryable's key (when it has no wildcard), `q.reply(key, payload, attachment:)` as before. Without a block, `each(timeout:)` yields the queries |
160
- | `s.get(key, timeout: 2.0, params:, payload:, attachment:, target:, consolidation:, errors: false, **opts)` | an Enumerator of `Reply`; each iteration sends the get again. With a block: yields each, returns their number. `errors: true` also yields the error replies (`reply.error?`); opts: `encoding:`, `priority:`, `congestion_control:`, `express:`, `accept_replies:` |
161
- | `s.liveliness(key)` | a token (`close`) |
162
- | `s.liveliness_watch(key) { \|key, alive\| }` | on the receiving thread; the tokens alive now come first. Without a block, `each` yields `Liveliness` (`key`, `alive?`) |
163
- | `s.liveliness_get(key, timeout: 2.0)` | the keys alive now (an Array) |
193
+ | `s.get(key, timeout: 2.0, params:, payload:, attachment:, target:, consolidation:, errors: false, depth: 1024, **opts)` | a `GetEnumerator` of `Reply`; each iteration sends the get again, and `dropped` / `received` / `errors` are those of the last one. With a block: yields each, returns their number. `depth:` the replies kept until taken (see [Queues](#queues)). `errors: true` also yields the error replies (`reply.error?`; left out by default, as `each_reply` does: look there when "nobody answers"); `consolidation: :none` keeps every reply (zenoh's own default is `:auto`). opts: `encoding:`, `priority:`, `congestion_control:`, `express:`, `accept_replies:`, `timeout_ms:` |
194
+ | `s.liveliness(key)` | a token (`close`). With a block: withdrawn after the block |
195
+ | `s.liveliness_watch(key, depth: 1024) { \|key, alive\| }` | on the receiving thread; the tokens alive now come first, in one burst. Without a block, `each` yields `Liveliness` (`key`, `alive?`). `pending` / `received` / `dropped` / `closed?` / `close` |
196
+ | `s.liveliness_get(key, timeout: 2.0, depth: 1024)` | the keys alive now (a `KeyList`: an Array with `dropped` and `received`; waits) |
164
197
  | `s.start` / `s.stop` / `s.running?` | receive on a thread of its own |
165
198
  | `s.run` | receive on this thread until `stop`, the connection closing, or Ctrl-C (returns nil) |
166
- | `s.on_error { \|error, where\| }` | what the blocks raise (`StandardError`); without a handler it is printed with `warn`. Receiving goes on |
167
- | `s.session`, `zid`, `peers`, `poll`, `closed?`, `close` | |
199
+ | `s.on_error { \|error, where\| }` | what the blocks raise (`StandardError`); without a handler it is printed with `warn`. Receiving goes on. `on_error` replaces the handler; every other `on_*` adds one |
200
+ | `s.session`, `zid`, `connection_count`, `poll`, `closed?`, `close` | (`peers` is the deprecated name of `connection_count`) |
168
201
 
169
202
  `Sample`, `Reply` (`key`, `payload`, `attachment`, and since 0.3.0 `kind`,
170
203
  `encoding`, `timestamp` and the rest; `text` is the payload as UTF-8; both
171
204
  are asterism-zenoh's) and `Liveliness` are `Data` values, so they work with pattern
172
- matching: `case sample in {key: %r{/temp\z}, payload:}`. Times are seconds
173
- here (the polled API counts milliseconds).
205
+ matching: `case sample in {key: %r{/temp\z}, payload:}`.
174
206
 
175
207
  ### Objects
176
208
 
@@ -191,12 +223,38 @@ end
191
223
  | `Asterism.connect(...) { \|net\| }` | yields an `Asterism::Net`, `Asterism.close` when the block ends; returns the block's value. Without a block, as before |
192
224
  | `Asterism.net` | the `Net` of the connection made without a block (nil when not connected) |
193
225
  | `net.expose` / `unexpose` / `exposed` | as `Asterism.expose`. The methods run on the receiving thread, in `run`, or in whatever polls |
194
- | `net[path, timeout: nil]` | a proxy (`timeout` in seconds) |
195
- | `net.each(pattern = "**")` | the proxies alive now; an Enumerator without a block |
196
- | `net.on_join { \|node\| }` / `net.on_leave { \|node\| }` | `Asterism.on_join` / `on_leave` of the polled API (the same blocks, told from `Asterism.poll`), here on the receiving thread; what they raise goes to `on_error` |
226
+ | `net[path, timeout: 2.0]` | a proxy (`timeout` in seconds, or `timeout_ms:`) |
227
+ | `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) |
228
+ | `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 |
197
229
  | `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 |
198
230
  | `net.nodes`, `node_id`, `app`, `connected?`, `lost_reason`, `poll`, `close` | |
199
231
 
232
+ ### Over TLS (a router on the internet)
233
+
234
+ `config:` of `Asterism.connect` (and of `Asterism::Zenoh.open`,
235
+ `Asterism::ROS.connect`) goes to the zenoh session: a Hash of zenoh's
236
+ configuration keys, or a JSON5 String (`File.read("client.json5")`). For a
237
+ router that asks for a client certificate (mutual TLS):
238
+
239
+ ```ruby
240
+ tls = {
241
+ "transport/link/tls/root_ca_certificate" => "certs/ca.pem", # the CA that signed the router
242
+ "transport/link/tls/connect_certificate" => "certs/cruby.pem", # this node's certificate
243
+ "transport/link/tls/connect_private_key" => "certs/cruby.key",
244
+ "transport/link/tls/enable_mtls" => true
245
+ }
246
+ Asterism.connect("tls/router.example.org:7448", node: "cruby", app: "demo", config: tls) do |net|
247
+ net["fmruby-aaaaaa/demo/info"].status # a board on the router's other side
248
+ end
249
+ ```
250
+
251
+ The router checks the certificate against its CA, and its ACL can tell the
252
+ nodes apart by the certificate's common name. The name in the locator must
253
+ be one the router's certificate is valid for (zenoh checks it; it is
254
+ `verify_name_on_connect`). `examples/node.rb --ca --cert --key` does the same.
255
+ The boards (zenoh-pico on ESP32) have no TLS: they stay on a router in their
256
+ own network, which connects to the outside one.
257
+
200
258
  ### ROS 2
201
259
 
202
260
  ```ruby
@@ -216,12 +274,12 @@ end
216
274
  | Call | Notes |
217
275
  |---|---|
218
276
  | `Asterism::ROS.connect(locator = nil, domain: 0, type_path: nil, mode:, listen:)` | opens a session; yields an `Asterism::ROS::Connection` and closes it after. `type_path:` adds directories to `TYPE_PATH` |
219
- | `ros.node(name, namespace: "/", enclave: "/")` | an `Asterism::ROS::Node` (every method of the polled API) with the calls below |
220
- | `node.subscribe(topic, type) { \|msg, info\| }` | the polled API's (run from `node.poll`), here on the receiving thread; `info` is the `Attachment` or nil. Without a block: a subscription whose `each(timeout: nil)` waits for `[msg, info]` (Enumerable) |
277
+ | `ros.node(name, namespace: "/", enclave: "/")` | an `Asterism::ROS::Node` (every method of the portable API) with the calls below |
278
+ | `node.subscribe(topic, type) { \|msg, info\| }` | the portable API's (run from `node.poll`), here on the receiving thread; `info` is the `Attachment` or nil. Without a block: a subscription whose `each(timeout: nil)` waits for `[msg, info]` (Enumerable) |
221
279
  | `node.topic(topic, type).each` | subscribes for the iteration and withdraws after it (`first(n)`, `break`, the time running out) |
222
- | `node.every(seconds) { }` | the polled API's timer (run from `node.poll`), here on the receiving thread; returns a `Timer` (`cancel`, `fired`) |
280
+ | `node.every(seconds) { }` / `node.every(ms: 500) { }` | the portable API's timer (run from `node.poll`), here on the receiving thread; returns a `Timer` (`cancel`, `fired`) |
223
281
  | `node.service(name, type) { \|req\| response }` | answered while the connection spins (or from `node.poll`). What the block raises goes to `on_error`, and that request gets no answer |
224
- | `node.call(name, type, request = nil, timeout: 2.0, **fields)` | waits for the response |
282
+ | `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)) |
225
283
  | `ros.spin` (`run`) / `start` / `stop` / `running?` / `on_error` / `close` | |
226
284
  | `ros.zenoh` | the `Asterism::Zenoh::Connection` underneath (same receiving thread) |
227
285
 
@@ -242,7 +300,7 @@ that is not bundled: generate it with `tools/asterism_msggen.rb -o DIR`
242
300
  block that takes long delays everything else that connection receives**:
243
301
  hand long work to a thread or a Queue of your own.
244
302
  - zenoh-c never calls Ruby: it fills the queues, and the receiving thread
245
- empties them every 2 ms (`interval:`) with the polled API.
303
+ empties them every 2 ms (`interval:`) with the portable API.
246
304
  - A tick of the receiving thread holds the connection's lock (a `Monitor`;
247
305
  for the object layer, which is one connection per process,
248
306
  `Asterism::LOCK`). The application's calls into the same layer take it
@@ -257,6 +315,23 @@ that is not bundled: generate it with `tools/asterism_msggen.rb -o DIR`
257
315
  thread ends by itself, and waiting calls raise as before.
258
316
  - Enumerators (`each`, `get`, `topic`) wait on the thread that iterates
259
317
  them.
318
+ - **Do not wait in a block.** On CRuby a block that calls and waits (a
319
+ proxy call, `node.call`) works, but delays every other block of that
320
+ connection; on a board it can overflow the stack ([Stack](#stack)).
321
+
322
+ What may be shared between threads:
323
+
324
+ | Object | Use from several threads? |
325
+ |---|---|
326
+ | `Asterism::Zenoh::Session` and its subscribers, queryables, gets, publishers, queriers (CRuby) | yes; each queued entry goes to exactly one taker |
327
+ | `Zenoh::Connection` | yes; its blocks run one at a time on the receiving thread |
328
+ | An Enumerator (`Subscription#each`, `Watch#each`, `get`, `topic`) | one thread per iteration |
329
+ | The object layer (`Asterism.*`, `Net`, proxies, `Future`) | yes; serialized by `Asterism::LOCK` (one connection per process) |
330
+ | `ROS::Connection` and the nodes it makes | yes (its runner's lock) |
331
+ | A `ROS::Node` made with `Node.new` (portable API) on CRuby | **no**: one thread, as on the boards |
332
+ | A session opened before `fork` | not in the child: its calls raise `Zenoh::ClosedError`; connect after fork |
333
+ | The boards | one thread (the application's update loop) |
334
+ | Ractors | not supported |
260
335
 
261
336
  ## License
262
337
 
@@ -276,10 +351,10 @@ RubyGems, and on mruby / PicoRuby the Zenoh binding is the separate mrbgem
276
351
 
277
352
  ---
278
353
 
279
- # The API
354
+ # The portable API
280
355
 
281
- The same on every Ruby (the polled API; CRuby adds the layer described in
282
- [The Ruby-like API](#the-ruby-like-api-cruby-only)). The examples use PicoRuby's `sleep_ms`; on CRuby
356
+ The same on every Ruby (CRuby adds the layer described in
357
+ [The CRuby API](#the-cruby-api)). The examples use PicoRuby's `sleep_ms`; on CRuby
283
358
  write `sleep`. When PicoRuby's `Machine` is there it is used for the clock
284
359
  and the short pauses while waiting; otherwise `Time` and `sleep`. Besides
285
360
  `Asterism::Zenoh`, the layers need a `MessagePack` module with `pack` /
@@ -298,6 +373,7 @@ apu.play("t120 o4 cdefg") # runs there, returns its value
298
373
  apu.respond_to?(:play) # => true (from the exposed list)
299
374
  f = apu.async.play("cde") # does not wait
300
375
  f.done?; f.value
376
+ Asterism["fmruby-bbbbbb/demo/apu", timeout: 5.0].play("c") # a longer time limit
301
377
  Asterism.each("*/*/apu") { |a| a.stop } # every apu alive now
302
378
  Asterism.nodes # => ["linux", "fmruby-bbbbbb"]
303
379
  ```
@@ -306,25 +382,124 @@ Asterism.nodes # => ["linux", "fmruby-bbbbbb"]
306
382
 
307
383
  | Call | Returns | Raises / notes |
308
384
  |---|---|---|
309
- | `Asterism.connect(locator, node:, app:, mode: nil, listen: nil)` | `Asterism` | `locator`, `mode:`, `listen:` go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to about 1.5 s for that check (a router answers at once). |
385
+ | `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). |
310
386
  | `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. |
311
387
  | `Asterism.unexpose(name)` | true / false | |
312
388
  | `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. |
313
- | `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`. `Asterism.close` forgets them (a lost connection does not). |
314
- | `Asterism[path, timeout_ms = 2000]` | `Proxy` | `path` is `<node>/<app>/<object>` without wildcards (`ArgumentError`). Nothing is sent until a method is called. |
315
- | `proxy.<method>(*args, **kw)` | the remote return value | Waits for the answer (`timeout_ms`). `RemoteError` when it raised there or could not be called (not exposed: `NoMethodError`; wrong number of arguments: `ArgumentError`; no such object: `NameError`), `Timeout` when no answer came in time (also at once when nobody answers that key), `Disconnected`, `EncodeError` (before anything is sent) for a value MessagePack cannot carry. A block cannot be sent (`ArgumentError`). |
389
+ | `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). |
390
+ | `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. |
391
+ | `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`). |
316
392
  | `proxy.async.<method>(...)` | `Future` | Sends and returns at once. `EncodeError` / `Disconnected` are raised here. |
317
393
  | `future.done?` | true / false | Never waits (`Asterism.poll` moves it on). True once the answer came, the time ran out or the connection closed. |
318
- | `future.value` | the return value | Waits (polling) if not done; raises like a waiting call. `future.took_ms`: time to the answer. |
319
- | `proxy.respond_to?(name)` / `proxy.methods` | true / false, `[Symbol]` | From the object's meta (fetched once, `proxy.asterism_refresh` forgets it). `respond_to?` is false when the object does not answer; `methods` raises then. |
394
+ | `future.value` | the return value | Waits (polling) if not done; raises like a waiting call. `future.took` (seconds) / `took_ms`: time to the answer. |
395
+ | `proxy.respond_to?(name)` / `proxy.remote_methods` | true / false, `[Symbol]` | From the object's meta (fetched once, `proxy.asterism_refresh` forgets it). `respond_to?` is false when the object does not answer; `remote_methods` raises then. (`proxy.methods` returns the same with a deprecation warning; from 1.0 it is `Object#methods`.) |
320
396
  | `proxy.asterism_meta` / `proxy.asterism_path` | Hash, String | `{"methods" => [[name, arity], ...]}` |
321
- | `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. |
397
+ | `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. |
322
398
  | `Asterism.nodes` | `[String]` | Node IDs alive now, this one first. |
323
399
  | `Asterism.connected?` / `node_id` / `app` / `exposed` / `lost_reason` | | |
324
400
  | `Asterism.close` | nil | Withdraws every exposed object. Idempotent. |
325
401
 
326
- Errors: `Asterism::Error` (base, a `StandardError`), `EncodeError`, `RemoteError`
327
- (`remote_class`, `remote_message`), `Timeout`, `Disconnected`.
402
+ ## Errors
403
+
404
+ Every error Asterism raises is an `Asterism::Error` (a `StandardError`):
405
+
406
+ ```
407
+ Asterism::Error (the Zenoh bindings define it)
408
+ ├── Asterism::Zenoh::Error (binding failures; #code is zenoh's result code)
409
+ │ └── Asterism::Zenoh::ClosedError (the session is closed or its connection was lost)
410
+ ├── Asterism::Disconnected (object layer: the connection is closed or lost)
411
+ ├── Asterism::TimeoutError (no answer in time; old name Asterism::Timeout)
412
+ │ └── Asterism::ROS::TimeoutError (old name Asterism::ROS::Timeout)
413
+ ├── Asterism::EncodeError
414
+ ├── Asterism::RemoteError (remote_class, remote_message)
415
+ ├── Asterism::ROS::UnknownType
416
+ ├── Asterism::CDR::DecodeError
417
+ └── Asterism::DeprecationError (only with Asterism.deprecations = :raise)
418
+ ```
419
+
420
+ The old names `Asterism::Timeout` and `Asterism::ROS::Timeout` still work
421
+ (they warn once). Inside `module Asterism`, `Timeout` is Ruby's `Timeout`
422
+ module again. The ROS layer raises `Zenoh::ClosedError` when its session
423
+ is closed (1.0: `Disconnected`, as the object layer).
424
+
425
+ ## Defaults
426
+
427
+ | What | Default | Changed by |
428
+ |---|---|---|
429
+ | A proxy call | 2 s | `Asterism[path, timeout:]` / `timeout_ms:`; `DEFAULT_TIMEOUT` (s), `DEFAULT_TIMEOUT_MS` |
430
+ | A service call | 2 s | `client.call(..., timeout:)` / `timeout_ms:`; `Client::DEFAULT_TIMEOUT` |
431
+ | `get`, `liveliness_get`, a querier | 2 s | `timeout:` / `timeout_ms:` |
432
+ | Connecting | 3 s | `connect_timeout:` (CRuby); `Zenoh::CONNECT_TIMEOUT_MS` (fixed at build time on the boards) |
433
+ | A send that cannot go out | 3 s | `Zenoh::SEND_TIMEOUT_MS` |
434
+ | The duplicate check of `Asterism.connect` | 1.5 s | `check_timeout:`; `CHECK_TIMEOUT` |
435
+ | Queue depth (subscriptions, queryables) | 16 (services 8; the object layer's queryable 32) | `depth:` |
436
+ | Queue depth of gets, liveliness gets and liveliness watches | CRuby 1024, the boards 16 (the object layer's watch: 1024 on CRuby, 64 on the boards) | `depth:`; `Zenoh::DEFAULT_GET_DEPTH`, `Zenoh::DEFAULT_WATCH_DEPTH` |
437
+ | A full queue | drops the oldest (counted in `dropped`); the CRuby API warns once | `depth:` |
438
+ | Pause between polls of a waiting call | 2 ms | `WAIT_STEP_MS`, `Client::WAIT_STEP_MS` |
439
+ | Receiving interval of the CRuby API | 2 ms | `interval:` |
440
+ | Calls waiting inside each other | 4 | `MAX_NESTING` |
441
+ | Encoding depth of a value | 16 | `Codec::MAX_DEPTH` |
442
+ | `get` consolidation | `:none` (every reply; zenoh's own default is `:auto`, but services and the object layer want every reply) | `consolidation:` |
443
+
444
+ ### Queues
445
+
446
+ Everything received waits in a bounded queue until taken; when it is full
447
+ the oldest entry goes and is counted in `dropped`. A router answers a
448
+ wildcard get or liveliness get, and a new liveliness watch, with
449
+ everything at once, so on CRuby those three queues hold 1024 by default
450
+ (they grow as entries come; nothing is allocated up front). On the boards
451
+ they stay at 16: a get's queue is allocated in full when it is sent (in
452
+ PSRAM on ESP-IDF) and a watch's comes from the VM's pool; pass `depth:`
453
+ when a wildcard can match more.
454
+
455
+ On CRuby, a get (`get`, `Querier#get`, `liveliness_get`), a liveliness
456
+ watch or a subscription of the CRuby API whose depth was left at the
457
+ default warns once (`asterism: get demo/**: 3 replies dropped, ...`) when
458
+ something was dropped; with `depth:` given it stays quiet, and `dropped`
459
+ tells. The object layer warns once when its own watch dropped changes
460
+ (then `Asterism.each` and `Asterism.nodes` may miss objects).
461
+ `Asterism.warn_once(obj, message)` is the helper.
462
+
463
+ Every `each_*` of the portable API (`each_pending`, `each_reply`,
464
+ `each_result`) takes what is there now, without waiting, and returns an
465
+ Array without a block (it drains the queue; an Enumerator would take only
466
+ when iterated).
467
+
468
+ ## Deprecations and 1.0
469
+
470
+ 0.4.0 adds and deprecates; nothing that worked in 0.3.0 stops working. A
471
+ deprecated call warns once per name (`warn` on CRuby, so it goes to
472
+ `$stderr`; on the boards `warn` or `puts`, once per VM).
473
+ `Asterism.deprecations = :raise` (or the environment variable
474
+ `ASTERISM_DEPRECATIONS=raise`) raises `Asterism::DeprecationError` instead,
475
+ for CI; `:silent` turns them off.
476
+
477
+ | Deprecated (0.4.0) | Use | In 1.0 |
478
+ |---|---|---|
479
+ | `Asterism[path, 2000]` (the time as a positional argument) | `Asterism[path, timeout: 2.0]` or `timeout_ms: 2000` | removed |
480
+ | A Float there (`Asterism[path, 2.0]` waits 2 ms) | `timeout: 2.0` | removed (warns with its own message now) |
481
+ | `session.get(key, ms, params, payload)`, `session.liveliness_get(key, ms)` | `timeout:` / `timeout_ms:`, `params:`, `payload:` | removed (a positional depth stays) |
482
+ | `session.peers`, `connection.peers` | `connection_count` | removed |
483
+ | `Asterism::Timeout`, `Asterism::ROS::Timeout` | `TimeoutError` | kept as aliases through 1.x |
484
+ | `proxy.methods` (the remote list) | `proxy.remote_methods` | `Object#methods` again |
485
+ | `Connection::Subscription#each_pending` (CRuby API; it gave Samples) | `each_sample` | removed |
486
+ | `q.reply(payload)` where the query's key differs from the queryable's own plain key | `q.reply(key, payload)` | answers on the queryable's key (as the CRuby API does) |
487
+ | `client.call(field: ...)` with a field named `timeout` / `timeout_ms` | `request: { ... }` (or a Hash) | the keyword is the time limit (`ArgumentError` when ambiguous) |
488
+
489
+ Also changing in 1.0, without a warning now: `Asterism.each { }` and
490
+ `net.each { }` return the proxies / `self` instead of a count; the ROS
491
+ layer raises `Disconnected` when its session is closed; the internal
492
+ methods (marked `@api private` in the source) are hidden.
493
+
494
+ ### Reserved keywords
495
+
496
+ `client.call` and `node.call` take the request's fields as keywords, next
497
+ to `request:`, `timeout:` and `timeout_ms:`. A request type with a field
498
+ of one of those names cannot be given that field as a keyword without
499
+ ambiguity: give the request as `request: { timeout: 5 }` (or a Hash /
500
+ message as the first argument) and the time limit as `timeout:`. In 0.4.0
501
+ the ambiguous keyword warns; on the portable API a `timeout:` field stays
502
+ a field, as before.
328
503
 
329
504
  ### When the connection is lost
330
505
 
@@ -409,15 +584,22 @@ nested type (`geometry_msgs/msg/Twist`) at start-up took 0.6 KB more.
409
584
  - The node token `asterism/<node>` is shared by every application of that
410
585
  node; when one of them closes, the others still list the node through
411
586
  their objects, but a watcher may see the node token go away.
412
- - No authentication: a trusted LAN is assumed.
413
- - Pattern matching on the boards: PicoRuby's compiler (checked on Family
414
- mruby's application VM) runs `case/in` with `deconstruct_keys`, nested
415
- hash patterns, array patterns, guards, alternatives, ranges, pins and
416
- `**rest`, but not two forms: a class as the value in a hash pattern
417
- (`in {x: Float}` does not match) and, inside a block, binding a variable
418
- of the enclosing method (`v = nil; list.each { |m| case m in {a: v} ... }`
419
- leaves it nil). Put the `case` in a method of its own, as in the example
420
- above.
587
+ - No authentication by default (plain TCP): a trusted LAN is assumed, or
588
+ TLS through a router (CRuby; [Over TLS](#over-tls-a-router-on-the-internet)).
589
+ - One object-layer connection per process (per VM on the boards).
590
+ - Pattern matching on the boards: `case/in` with `deconstruct_keys`, nested
591
+ hash patterns, classes and ranges as values, array and find patterns,
592
+ guards, alternatives, pins of a local of the same scope and binding from
593
+ inside a block work with the compiler of mruby-compiler2 `a2c72afb` or
594
+ later (PicoRuby master), and in Family mruby, which carries the two fixes
595
+ on its older PicoRuby. An older PicoRuby compares a hash pattern's value
596
+ the wrong way round (a class or a range never matches, a literal matches
597
+ any value) and does not bind an outer variable from inside a block;
598
+ there, match on the key alone and test the value in Ruby. Still
599
+ different on Family mruby's PicoRuby: `^x` of an outer local inside a
600
+ block, `^(expr)`, `Const[...]` and `**rest` next to another key. The full
601
+ list of what the boards' Ruby can and cannot do is in
602
+ [docs/ruby_profile.md](docs/ruby_profile.md).
421
603
 
422
604
  ## ROS 2 (rmw_zenoh): `Asterism::ROS` and `Asterism::CDR`
423
605
 
@@ -442,7 +624,7 @@ loop do
442
624
  end
443
625
 
444
626
  # or with blocks, run from node.poll (in the update loop):
445
- node.every(1) { pub << { data: "tick" } }
627
+ node.every(1) { pub << { data: "tick" } } # or every(ms: 1000)
446
628
  node.subscribe("/cmd_vel", "geometry_msgs/msg/Twist") { |msg, _info| drive(msg) }
447
629
  loop { node.poll }
448
630
 
@@ -462,7 +644,7 @@ node.service("/fmruby/add_two_ints", add) { |req| { sum: req.a + req.b } }
462
644
  cli = node.client("/add_two_ints", add)
463
645
  loop do
464
646
  node.poll # session.poll, then answers the requests
465
- res = cli.call(a: 2, b: 3) # waits (polling), raises Asterism::ROS::Timeout
647
+ res = cli.call(a: 2, b: 3) # waits (polling), raises Asterism::ROS::TimeoutError
466
648
  puts res.sum
467
649
  c = cli.call_async(a: 2, b: 3) # returns at once
468
650
  # ... later updates:
@@ -476,15 +658,15 @@ end
476
658
  | `node.publisher(topic, type, qos: DEFAULT_QOS)` | `Publisher` | `topic` absolute, or relative to the namespace. `type` is a generated type or its ROS name (`"geometry_msgs/msg/Twist"`, loaded with `require_type`); the same for subscriptions, services and clients. Declares the publisher token (`ros2 topic list`). |
477
659
  | `pub.publish(msg)` / `pub << msg` | nil / `pub` | `msg` is a message of the type or a Hash of its fields. Puts the CDR payload with rmw_zenoh's attachment (sequence number, time, GID). |
478
660
  | `node.subscription(topic, type, qos: DEFAULT_QOS, depth: 16)` | `Subscription` | Subscribes and declares the subscription token. |
479
- | `sub.each_pending { \|msg, info\| }` | count | `info` is an `Attachment` (`sequence`, `stamp_ns`, `gid`) or nil. Samples that are not valid CDR are skipped and counted in `sub.errors`. |
661
+ | `sub.each_pending { \|msg, info\| }` | count | `info` is an `Attachment` (`sequence`, `stamp_ns`, `gid`) or nil. Samples that are not valid CDR are skipped and counted in `sub.errors`. `sub.pending` / `received` / `dropped` count as the Zenoh subscriber's do. |
480
662
  | `node.service(name, type, qos: DEFAULT_QOS, depth: 8) { \|req\| response }` | `Service` | Serves `name` (`ros2 service list`). The block gets a `type::Request` and returns a `type::Response` or a Hash of its fields. It runs from `node.poll` (or `service.handle_pending`), never behind the application. A request without rmw_zenoh's attachment, or that does not decode, is counted in `service.errors` and gets no answer. An exception from the block ends that request without an answer and is raised from `node.poll`. `service.handled`: answered so far. |
481
663
  | `node.poll(steps = 8)` | true / false | `session.poll(steps)`, then answers the requests waiting for this node's services, then gives what came to the `subscribe` blocks and fires the `every` timers that are due. Returns what `session.poll` returns. A waiting `client.call` polls only the session and the services (`node.pump`), not the blocks. |
482
- | `node.subscribe(topic, type, qos: DEFAULT_QOS, depth: 16) { \|msg, info\| }` | `Subscription` | `node.subscription` whose messages (decoded, with their `Attachment` or nil) go to the block, from `node.poll`. `sub.close` ends it. Do not wait in the block (see [Stack](#stack)). |
483
- | `node.every(seconds) { }` | `Timer` | Calls the block every `seconds` (a Float works), the first time one period from now, from `node.poll` (so no more often than the update loop polls). It keeps the period; after a long stall it starts again from now instead of firing the missed times at once. `timer.cancel`, `timer.fired` (count), `timer.period`. Do not wait in the block. |
664
+ | `node.subscribe(topic, type, qos: DEFAULT_QOS, depth: 16) { \|msg, info\| }` | `Subscription` | `node.subscription` whose messages (decoded, with their `Attachment` or nil) go to the block, from `node.poll`. `sub.close` ends it. Do not wait in the block (see [Stack](#stack)). Without a block it is `node.subscription`. |
665
+ | `node.every(seconds) { }` / `node.every(ms: 500) { }` | `Timer` | Calls the block every `seconds` (a Float works) or `ms:` milliseconds, the first time one period from now, from `node.poll` (so no more often than the update loop polls). It keeps the period; after a long stall it starts again from now instead of firing the missed times at once. `timer.cancel`, `timer.fired` (count), `timer.period` (s), `timer.period_ms`. Do not wait in the block. |
484
666
  | `node.client(name, type, qos: DEFAULT_QOS)` | `Client` | Declares the client token. |
485
- | `client.call(request = nil, timeout_ms: 2000, **fields)` | `type::Response` | Sends the request (a `type::Request`, a Hash, or the fields as keywords) and waits, polling the node (its services keep answering). `Asterism::ROS::Timeout` when no response came in time, at once when nobody serves the name; `Asterism::Zenoh::Error` when the session closed. |
486
- | `client.call_async(request = nil, timeout_ms: 2000, **fields)` | `Call` | Sends and returns at once. `call.done?` never waits (`node.poll` moves it on); `call.value` waits and returns the response or raises like `call`; `call.response` (nil until it came), `call.took_ms`, `call.sequence`. |
487
- | `node.call(name, type, request = nil, timeout_ms: 2000, **fields)` | `type::Response` | `client.call` through a client made on first use and kept per name. |
667
+ | `client.call(request = nil, request: nil, timeout: 2.0, **fields)` | `type::Response` | Sends the request (a `type::Request` or a Hash, positional or `request:`, or the fields as keywords) and waits, polling the node (its services keep answering). The time limit: `timeout:` (seconds) or `timeout_ms:`. `Asterism::ROS::TimeoutError` when no response came in time, at once when nobody serves the name; `Asterism::Zenoh::ClosedError` when the session closed. See [Reserved keywords](#reserved-keywords). |
668
+ | `client.call_async(...)` | `Call` | The same arguments; sends and returns at once. `call.done?` never waits (`node.poll` moves it on); `call.value` waits and returns the response or raises like `call`; `call.response` (nil until it came), `call.took` (s) / `took_ms`, `call.sequence`. |
669
+ | `node.call(name, type, request = nil, request:, timeout:, **fields)` | `type::Response` | `client.call` through a client made on first use and kept per name. |
488
670
  | `node.close` / `pub.close` / `sub.close` / `service.close` / `client.close` | nil | Withdraws the tokens (they also go when the session closes). `node.close` closes everything the node made. |
489
671
  | `Asterism::ROS.require_type(name)` | the type | Loads `<pkg>/<msg\|srv>/<Name>.rb` from `Asterism::ROS::TYPE_PATH` (`["/usr/share/asterism/msgs"]`; add directories to it) and returns `Asterism::ROS::<Pkg>::<Name>`. A type already loaded (or defined in Ruby) is returned at once. `UnknownType` when there is no file. |
490
672
  | `Asterism::CDR::Writer` / `Reader` | | Plain CDR with the 4-byte header, aligned from the end of the header: `bool int8 uint8 int16 uint16 int32 uint32 int64 uint64 float32 float64 string`, `array(kind, v, fixed, max)`, `bytes`, `structs(type, ...)`. Writes little endian; reads either order. |