pebble
  • Tutorials
  • Get the SDK
  • Guides
  • Documentation
  • PebbleOS
  • Mobile App
  • Examples
  • Index 01
  • Community
  • Blog
  • More
Privacy
Cookies
Publish

PebbleOS

  • Overview
  • Start here
    • Getting started guide
    • Playground
  • Development
    • The pbl CLI
    • Build system
    • Emulator and simulator
    • Testing
    • Debugging
    • Conventions
  • System
    • Architecture overview
    • Kernel
    • Subsystems
      • Analytics
      • Bluetooth
      • Core dumps
      • CRC
      • File system
      • Internationalization
      • Input
      • Logging
      • Pebble protocol
      • Profiler
      • Shell
      • Console
      • Task watchdog
    • Drivers
    • Services
    • Libraries
    • Third-party
    • Application SDK
  • Hardware
    • Boards
    • Programmers
  • Community
    • Contribution Guidelines
  • Reference
    • Reference
    • Kconfig options

Shell

subsys/shell/ is the debug command shell. Its public API is include/pbl/shell/shell.h, and backends implement include/pbl/shell/backend.h. Commands are defined next to the code they drive, collected at link time, and served by any number of shell instances, one per backend.

Commands

A command is a struct pbl_shell_cmd: a name, a help string, a handler and optionally a table of subcommands, so commands form a tree (bt disc start).

  • PBL_SHELL_CMD_REGISTER() / PBL_SHELL_CMD_ARG_REGISTER() register a root command from any file. The entries land in the .pbl_shell_root_cmds linker section, sorted by name.

  • A file-local subcommand table is a plain struct pbl_shell_cmd array of PBL_SHELL_CMD() entries ending with PBL_SHELL_SUBCMD_SET_END.

  • PBL_SHELL_SUBCMD_SET_CREATE() builds a subcommand set that other files extend with PBL_SHELL_SUBCMD_ADD(), without referencing any symbol of the owner. The entries live in .pbl_shell_subcmds.<set>.<name> input sections, sorted between a start marker and a terminator, so a set is a contiguous, NULL-terminated array once linked. This is how, for instance, the Bluetooth, console and driver code all add to bt or flash.

Handlers get argc/argv with argv[0] being the matched command name. mandatory (which counts argv[0]) and optional let the core check the argument count; -h/--help, unknown subcommands and commands without a handler print the help of the matched node. A handler returns 0 or a negative errno; -EINPROGRESS keeps the shell busy until pbl_shell_cmd_done(), for commands that finish from a callback.

Shell code is wrapped in #ifdef CONFIG_SHELL, and modules with a group of commands can gate them further; for example drivers/imu/shell.c builds with CONFIG_IMU_SHELL. Such options are off by default, as most of these commands are bring-up tools; only the commands the integration tests rely on are built with CONFIG_SHELL alone. CONFIG_DRIVER_SHELL and CONFIG_SUBSYS_SHELL turn on every driver or subsystem command group at once, e.g. pbl configure --board obelix@pvt -DCONFIG_DRIVER_SHELL=y.

static int prv_accel_read(const struct pbl_shell *sh, size_t argc, char **argv) {
  ...
  pbl_shell_print(sh, "x=%d y=%d z=%d mg", sample.x, sample.y, sample.z);
  return 0;
}

static const struct pbl_shell_cmd sub_accel[] = {
  PBL_SHELL_CMD(read, NULL, "Read one sample", prv_accel_read),
  PBL_SHELL_SUBCMD_SET_END,
};

PBL_SHELL_CMD_REGISTER(accel, sub_accel, "Accelerometer", NULL);

Instances and backends

PBL_SHELL_DEFINE() creates an instance bound to a backend. Every instance has its own line buffer and state, and commands receive the instance they run on, so their output goes back where the command came from. Commands of every instance run on SysWorkq.

  • Interactive instances (with a prompt) feed received characters with pbl_shell_input_from_isr(). The core does line editing, echo, the prompt and tab completion of command names on SysWorkq.

  • Line instances (no prompt) submit whole command lines with pbl_shell_execute_line(), and get a done callback when the command finishes.

The firmware’s backend is subsys/console/console.c, interactive, on the Console: the shell is always listening, and log lines print above the prompt, which comes back with the line being edited.

Release firmware has no shell: it needs CONFIG_CONSOLE, which is off there unless it is manufacturing firmware.

Generated from PebbleOS f3212a729. This page is maintained in the pebbleos repository: docs/subsystems/shell.md.

Overview

  • Commands
  • Instances and backends