Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dynamic help from agents #333

Merged
merged 4 commits into from
Dec 5, 2024
Merged

Dynamic help from agents #333

merged 4 commits into from
Dec 5, 2024

Conversation

mchitre
Copy link
Member

@mchitre mchitre commented Nov 29, 2024

This PR adds support for dynamic help text from agents using a __doc__ parameter in addition to normal help that shell extensions provide. An agent publishing __doc__ must advertise the org.arl.fjage.shell.Services.DOCUMENTATION service. A placeholder @@ in the help text from an agent is replaced with the agent name. This permits writing of help without making assumption on agent name, or having to dynamically generate the help text.

Some changes in how help is displayed:

  • Help index is now sorted, so if 2 sources have similar help titles, they appear together.
  • If multiple sources have the same help title keyword then the helps are concatenated when shown to the user. This enables generic help for a service and specific help from an agent providing the service to be displayed together.
  • Auto generated lists use * as bullet.
  • Top-level headings retain # prefix to demarcate sections.

Example:

> help
arp - access to address resolution service
bb - access to baseband service
mac - CSMA MAC
mac - access to medium access control (MAC) service
node - access to node information service
phy - access to physical service
shell - basic shell commands
unet - basic unet commands

> help mac
# mac - access to medium access control (MAC) service

The MAC service provides access to medium access control parameters and functions.
Agents offering the medium access control (MAC) service advise other agents on
when they may be permitted to make transmissions, in an effort to reduce collisions
and improve network throughput.

Examples:
 mac                                            // list MAC parameters
 mac << new ReservationReq(to: 27, duration: 1) // channel reservation request

Parameters:

* mac.channelBusy - indicates if the channel is busy
* mac.reservationPayloadSize - size of payload (bytes) carried in MAC PDU
* mac.ackPayloadSize - size of ack payload (bytes) carried in ACK PDU
* mac.maxReservationDuration - maximum reservation duration
* mac.recommendedReservationDuration - recommended reservation duration

# mac - CSMA MAC

Parameters:

* mac.phy - physical agent used for carrier sensing
* mac.minBackoff - minimum backoff window (seconds)
* mac.maxBackoff - maximum backoff window (seconds)
* mac.reservationsPending - number of reservations in queue (read-only)

@mchitre mchitre requested a review from notthetup November 29, 2024 05:37
@mchitre mchitre self-assigned this Nov 29, 2024
@mchitre mchitre force-pushed the dynhelp branch 2 times, most recently from 85a3301 to a4a8b5e Compare December 5, 2024 11:23
@mchitre
Copy link
Member Author

mchitre commented Dec 5, 2024

@notthetup I have updated the PR to only look for docs in agents that publish DOCUMENTATION service. This avoids asking and timing out on agents that don't respond to requests (e.g. gateway agents).

@mchitre mchitre requested a review from notthetup December 5, 2024 11:28
@mchitre mchitre merged commit d50571f into master Dec 5, 2024
2 checks passed
@mchitre mchitre deleted the dynhelp branch December 5, 2024 12:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants