Robot State

The RobotState descriptor gives you access to sensor data—camera images, odometry, maps, and more. Declared state is automatically updated at 50Hz while your skill runs.

Declaration

Declare state dependencies as class attributes:

from brain_client.skill_types import Skill, RobotState, RobotStateType

class MySkill(Skill):
    image = RobotState(RobotStateType.LAST_MAIN_CAMERA_IMAGE_B64)
    odom = RobotState(RobotStateType.LAST_ODOM)

The system injects and updates these values automatically. Always check for None on first access.

Available State

Camera Image

The main camera image as a base64-encoded JPEG:

class MySkill(Skill):
    image = RobotState(RobotStateType.LAST_MAIN_CAMERA_IMAGE_B64)

    def execute(self):
        if not self.image:
            return "No image available", SkillResult.FAILURE

        # Decode base64 to bytes
        import base64
        image_bytes = base64.b64decode(self.image)

        # Use with PIL
        from PIL import Image
        import io
        img = Image.open(io.BytesIO(image_bytes))

        # Or send to vision API
        response = vision_api.analyze(self.image)

Odometry

Where the robot is and how it is moving, as an innate.Odometry object. MARS is a differential-drive base on flat ground, so you get a flat 2D pose — x, y, and a yaw angle — directly, no quaternion math needed:

class MySkill(Skill):
    odom = RobotState(RobotStateType.LAST_ODOM)

    def execute(self):
        if self.odom:
            x, y = self.odom.position          # meters, odom frame
            heading = self.odom.theta_degrees  # yaw, counter-clockwise positive
            speed = self.odom.linear_velocity  # m/s, forward

Attribute	Type	Description
`x`, `y`	`float`	Position in meters, odom frame
`position`	`tuple[float, float]`	`(x, y)` shorthand
`theta`	`float`	Yaw in radians, counter-clockwise positive, wrapped to `(-pi, pi]`
`theta_degrees`	`float`	Yaw in degrees (matches `navigate_to_position`’s `theta_degrees`)
`linear_velocity`	`float`	Forward speed in m/s (negative when reversing)
`angular_velocity`	`float`	Turn rate in rad/s, counter-clockwise positive
`stamp`	`float`	Sensor timestamp in seconds
`raw`	`dict`	The full `nav_msgs/Odometry` as plain data

Always check for None on first access — the first odometry message is one publish period away when a skill starts.

Closing a loop on odometry

Declared state refreshes at 50 Hz while your skill runs, so you can read the attributes in a loop to close a control loop. This drives forward a fixed distance by watching position:

import math
import time
from innate import Interface, InterfaceType, RobotState, RobotStateType, Skill, SkillResult

class DriveMeters(Skill):
    mobility = Interface(InterfaceType.MOBILITY)
    odom = RobotState(RobotStateType.LAST_ODOM)

    @property
    def name(self):
        return "drive_meters"

    def execute(self, distance: float = 0.5):
        if self.odom is None:
            return "No odometry", SkillResult.FAILURE

        start = self.odom.position                      # (x, y) snapshot
        while math.dist(self.odom.position, start) < distance:
            if self._cancelled:
                self.mobility.send_cmd_vel(linear_x=0.0)
                return "Cancelled", SkillResult.CANCELLED
            # duration acts as a deadman: if this loop dies, the base stops
            self.mobility.send_cmd_vel(linear_x=0.15, duration=0.5)
            time.sleep(0.1)

        self.mobility.send_cmd_vel(linear_x=0.0)
        return f"Drove {distance:.2f}m", SkillResult.SUCCESS

For heading, theta_degrees is already wrapped to (-180, 180]. Accumulate wrapped deltas so a turn across the ±180° seam still counts correctly:

last = self.odom.theta_degrees
turned = 0.0
while turned < 90.0:
    self.mobility.send_cmd_vel(angular_z=0.5, duration=0.5)
    time.sleep(0.05)
    now = self.odom.theta_degrees
    turned += (now - last + 180.0) % 360.0 - 180.0      # signed shortest-arc delta
    last = now

Checking freshness

Use stamp (seconds) to skip a reading that has gone stale — for example after a feed hiccup, when the 50 Hz refresh would otherwise hand you a frozen value:

age = time.time() - self.odom.stamp
if age > 0.5:
    return f"Odometry stale ({age:.1f}s old)", SkillResult.FAILURE

Need more than the 2D pose?

odom.raw carries the complete odometry message with rosbridge-style keys — the real quaternion, z, covariances, and the full twist — for skills doing their own filtering or fusion:

class FusePose(Skill):
    odom = RobotState(RobotStateType.LAST_ODOM)

    @property
    def name(self):
        return "fuse_pose"

    def execute(self):
        if self.odom is None:
            return "No odometry", SkillResult.FAILURE

        raw = self.odom.raw                              # full nav_msgs/Odometry as a dict
        quat = raw["pose"]["pose"]["orientation"]        # {"x", "y", "z", "w"} — true quaternion
        z = raw["pose"]["pose"]["position"]["z"]         # height (not on the flat API)
        pose_cov = raw["pose"]["covariance"]             # 36 floats, row-major 6x6
        lateral = raw["twist"]["twist"]["linear"]["y"]   # sideways velocity

        # e.g. reject a fix whose position variance is too high
        if pose_cov[0] > 0.25:                           # var(x) > 0.25 m²
            return "Pose too uncertain", SkillResult.FAILURE

        return f"z={z:.3f} lateral={lateral:.3f}", SkillResult.SUCCESS

Skills written for 0.3.0 through 0.6.x read odometry as a raw-message dict (self.odom["theta_degrees"], self.odom["pose"]["pose"]["position"]). Dict-style access is kept as a permanent compatibility layer — those skills keep working with no scheduled removal. New skills should use the attributes above.

Map

The occupancy grid map:

class MySkill(Skill):
    map_data = RobotState(RobotStateType.LAST_MAP)

    def execute(self):
        if self.map_data:
            width = self.map_data.info.width
            height = self.map_data.info.height
            resolution = self.map_data.info.resolution
            data = self.map_data.data  # 1D array of occupancy values

Head Position

Current head tilt angle:

class MySkill(Skill):
    head_pos = RobotState(RobotStateType.LAST_HEAD_POSITION)

    def execute(self):
        if self.head_pos:
            current_angle = self.head_pos
            # Returns int: -25 to +15

Example: CaptureImages

A skill that captures images while rotating:

from brain_client.skill_types import (
    Skill, SkillResult, Interface, InterfaceType, RobotState, RobotStateType
)
import math

class CaptureImages(Skill):
    mobility = Interface(InterfaceType.MOBILITY)
    image = RobotState(RobotStateType.LAST_MAIN_CAMERA_IMAGE_B64)

    @property
    def name(self):
        return "capture_images"

    def guidelines(self):
        return "Use to capture images from multiple directions."

    def execute(self, num_directions: int = 4):
        images = []
        rotation_step = (2 * math.pi) / num_directions

        for i in range(num_directions):
            if self._cancelled:
                return "Capture cancelled", SkillResult.CANCELLED

            # Capture current frame
            if self.image:
                images.append(self.image)
                self._send_feedback(f"Captured {i+1}/{num_directions}")

            # Rotate to next position
            if i < num_directions - 1:
                self.mobility.rotate(rotation_step)

        return f"Captured {len(images)} images", SkillResult.SUCCESS

    def cancel(self):
        self._cancelled = True
        return "Capture cancelled"

Example: MonitorPosition

A skill that tracks robot movement:

from brain_client.skill_types import Skill, SkillResult, RobotState, RobotStateType
import math
import time

class MonitorPosition(Skill):
    odom = RobotState(RobotStateType.LAST_ODOM)

    @property
    def name(self):
        return "monitor_position"

    def guidelines(self):
        return "Use to monitor robot position for a duration."

    def execute(self, duration: float = 5.0):
        if not self.odom:
            return "Odometry not available", SkillResult.FAILURE

        start = self.odom.position
        start_time = time.time()

        while time.time() - start_time < duration:
            if self._cancelled:
                return "Monitoring cancelled", SkillResult.CANCELLED

            distance = math.dist(self.odom.position, start)

            self._send_feedback(f"Moved {distance:.2f}m from start")
            time.sleep(0.5)

        return f"Monitoring complete", SkillResult.SUCCESS

    def cancel(self):
        self._cancelled = True
        return "Monitoring cancelled"

Get Started

MARS Hardware

Controller App

Web App

Agent SDK

Hacking on MARS

Manipulation

ROS2 Core

Troubleshooting & Support

Hackathon

Declaration

Available State

Camera Image

Odometry

Closing a loop on odometry

Checking freshness

Need more than the 2D pose?

Map

Head Position

Example: CaptureImages

Example: MonitorPosition

​Declaration

​Available State

​Camera Image

​Odometry

​Closing a loop on odometry

​Checking freshness

​Need more than the 2D pose?

​Map

​Head Position

​Example: CaptureImages

​Example: MonitorPosition

Declaration

Available State

Camera Image

Odometry

Closing a loop on odometry

Checking freshness

Need more than the 2D pose?

Map

Head Position

Example: CaptureImages

Example: MonitorPosition