`ros_sugar.robot.mapping`#

Mapping capability descriptors.

A robot plugin declares how maps of its environment get built. Mapping is a one-off, operator-driven activity that produces a file on disk, so it is driven from the EMOS CLI.

A declaration is read through python -m ros_sugar.robot inspect.

Two kinds:

VendorMapping – the robot ships its own SLAM, reached by running a vendor tool. The plugin supplies the argv and where the results land.
NativeMapping – EMOS maps the environment itself from the plugin’s own LiDAR and IMU feedbacks.

A plugin that declares neither simply cannot be mapped, and the CLI says so.

Module Contents#

Classes#

`VendorMapping`	Mapping performed by the robot’s own software.
`NativeMapping`	Mapping performed by EMOS from the plugin’s own sensor feedbacks.

API#

class ros_sugar.robot.mapping.VendorMapping#

Bases: ros_sugar.config.BaseAttrs

Mapping performed by the robot’s own software.

The commands are argv lists rather than shell strings. {name} is substituted with the map name at call time.

Parameters:

start – Begin a mapping session.
stop – End the session and save. A clean exit code does not mean the map was written – what settles it is the map appearing in the store.
stop_retries – How many extra times to re-issue stop if the map has not appeared. Only for vendors that document stop as safe to repeat and sometimes needing it; the default of 0 issues it once.
store – Directory holding every map on the robot.
grid – Occupancy-grid YAML filename inside a map directory. The default is the ROS map_server convention, which is also what Kompass’s MapServer loads.
cloud – Point-cloud filename inside a map directory.
apply – Make a map the active one. None if the vendor offers no such command.
after_apply – Run after apply – typically restarting the vendor’s localization service, without which the switch silently does not take effect.
export – Package a map for copying off the robot. Vendors commonly only package the active map and take no argument, so {name} and {path} are optional here.
export_dir – Where export leaves the archive, when the vendor chooses the path itself. Empty means unknown, and the caller reports only that the command ran.
import_ – Unpack an archive produced by export into the store. {path} is substituted with the archive’s absolute path. Trailing underscore because import is a keyword; it is import in spec.
remove – Delete a map. None where the vendor offers no such command, in which case the map directory is removed directly.
active_link – Name of the symlink in store pointing at the active map.
requires_root – Whether any command here escalates privilege. Purely a capability hint: the dashboard cannot drive such a provider, because its daemon has no terminal for a password prompt, so it directs the operator to the CLI instead. It does not shape the commands – escalation belongs in the argv, because it is per-verb. DEEP Robotics, for instance, documents sudo on mapping and apply but not on pack, and prefixing it anyway would leave a root-owned archive the operator cannot delete.
host – "local" when the commands run on the machine EMOS is installed on, otherwise "ssh://user@host".
area_limit_m – Largest square area the vendor supports, in metres, if documented. Advisory only; shown to the operator before they start.

active_grid_path() → Optional[str]#

Absolute path of the active map’s occupancy-grid YAML, or None.

grid is preferred when it names a file that exists, otherwise the sole .yaml in the directory is taken; an ambiguous directory returns None rather than guessing.

property kind: str#: Discriminator for consumers reading a describe tree.

spec() → Dict[str, Any]#: JSON-serializable introspection record, tagged with kind.

asdict(filter: Optional[Callable] = None) → Dict#

to_dict() → Dict#

asdict_explicit() → Dict#

from_dict(dict_obj: Dict) → None#

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

to_json() → Union[str, bytes, bytearray]#

from_json(json_obj: Union[str, bytes, bytearray]) → None#

has_attribute(attr_name: str) → bool#

get_attribute_type(attr_name: str) → Optional[type]#

update_value(attr_name: str, attr_value: Any) → bool#

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

class ros_sugar.robot.mapping.NativeMapping#

Bases: ros_sugar.config.BaseAttrs

Mapping performed by EMOS from the plugin’s own sensor feedbacks.

The inputs are named by feedback key, not by topic, so the plugin stays the single source of truth for what the topic actually is and a topic rename does not invalidate this declaration.