FlaminGO-Light Python SDK

FlmainGO-Light Python SDK

1. Getting Started

1.1 How to Connect via SSH

When you power on the robot, a Wi-Fi hotspot is automatically enabled. You can connect to the robot through the enabled Wi-Fi.

SSID	COCELO_ROBOT_XXXX
Password	00000000

XXXX is a unique 4-character alphanumeric tag for each robot.

SSH Connection

# 1) Connect to Wi-Fi (connect to the COCELO_ROBOT_XXXX network)
# 2) SSH connection
ssh cocelo@XXXX    # XXXX = same tag as the Wi-Fi SSID
                   # Password: 00000000

---

1.2 Quick Drive Test

Connect the Joystick

1. Press and hold the joystick’s center Home button for at least 5 seconds.

2. Wait until pairing is complete.

If the joystick does not connect, fully charge it to 100% and try again.

Wake/Control the Robot

Run Example

cocelo run example

• Use the controller’s left stick to control the robot’s movement.

• Exit: Ctrl + C

When you exit, the motors stop immediately. Be sure to hold the handle and support the robot before exiting.

---

1.3 View Execution Logs

Command	Description
cocelo log list	View the list of saved log files
cocelo log show last	View the most recent log
cocelo log show <filename>	View a specific log file

Log Command Examples

cocelo log list
cocelo log show last
cocelo log show <filename>

---

2. SDK Preview

The example below shows the core SDK usage flow.

play.py

from flamingo_light_sdk import *

# 1) Robot gain settings
kp = [15, 15, 0, 0]
kd = [0.45, 0.45, 0.3, 0.3]

# 2) Define RL mode (policy and observation settings)
mode = Mode(mode_cfg={
    "id": 1,
    "stacked_obs_order": ["dof_pos", "dof_vel", "ang_vel", "proj_grav", "last_action"],
    "non_stacked_obs_order": ["command"],
    "obs_scale": {
        "dof_vel": 0.15,
        "ang_vel": 0.25,
        "command": [2.0, 0.0, 0.25, 0.0],
    },
    "action_scale": [0.85, 0.85, 40.0, 40.0],
    "stack_size": 3,
    "policy_path": "your_policy.onnx",
    "cmd_vector_length": 4,
})

# 3) Create instances
robot = Robot()
joystick = Joystick(max_cmd=[0.5, 0, 1, 0])
rl = RL()

# 4) Initialize
robot.set_gains(kp=kp, kd=kd)
rl.add_mode(mode)
rl.set_mode(mode_id=1)

# 5) Control loop (50Hz)
@control_rate(robot, hz=50)
def loop():
    obs = robot.get_obs()              # Acquire sensor data
    cmd = joystick.get_cmd()           # Acquire joystick commands
    state = rl.build_state(obs, cmd)   # Build state for inference
    action = rl.select_action(state)   # Policy inference
    robot.do_action(action)            # Send motor commands

loop()

Typical control loop order: get_obs() → get_cmd() → build_state() → select_action() → do_action()

---

3. Package Structure

Core Components

Component	Role
Robot	Robot interface
Joystick	Provides joystick input as cmd
Mode	Policy (.onnx)+ observation/scale/stack settings
RL	Builds network input state from obs + cmd + selects actions
control_rate	Runs the control loop at a specified rate

---

4. API Reference

Package Contents

flamingo_light_sdk

• Robot

• Joystick

• Mode

• ModeConfig

• RL

• control_rate

flamingo_light_sdk.onnxpolicy

• MLPPolicy

• LSTMPolicy

Exceptions

• RobotInitError

• RobotSetGainsError

• RobotEStopError

• ModeConfigError

---

flamingo_light_sdk

class flamingo_light_sdk.Robot()

class Robot()

Controls the hardware interface. It reads sensor observations and sends motor commands.

Quickstart

Basic Robot Usage

from flamingo_light_sdk import *

robot = Robot()                       # Create a Robot instance
robot.set_gains(kp=[...], kd=[...])   # Set PD gains
obs = robot.get_obs()                 # Acquire sensor data
robot.do_action([0, 0, 0, 0])         # Send motor commands
robot.estop()                         # Emergency stop

Joint Indices

Attributes

gains_set: bool

Whether gains have been set.

---

Robot()

Creates a robot instance.

Raises

• RobotInitError: Initialization failed

---

set_gains(kp: list[float], kd: list[float]) -> None

Sets PD gains for the 4 motors (joints).

Parameters

• kp (list[float]): Proportional gains (length 4)

• kd (list[float]): Derivative gains (length 4)

set_gains Example

#set_gains example
#Order: left shoulder, right shoulder, left wheel, right wheel

kp = [15, 15, 0, 0]
kd = [0.45, 0.45, 0.3, 0.3]

robot.set_gains(kp=kp, kd=kd)

The motor order corresponding to the gains in the kp/kd lists must match the following exactly.

Index 0: Left joint motor

Index 1: Right joint motor

Index 2: Left wheel motor

Index 3: Right wheel motor

Raises

• RobotSetGainsError

---

get_obs() -> dict

Returns the current sensor data.

get_obs Example

obs = robot.get_obs()
print(obs)
# Example: {"dof_pos": [...], "dof_vel": [...], "ang_vel": [...], "proj_grav": [...]}

---

do_action(action: list[float], torque_ctrl: bool = False) -> None

Sends motor commands.

Parameters

• action (list[float]): Target values (or torque values) for 4 motors

• torque_ctrl (bool, optional): If True, torque control mode

Basic Control

Position (shoulder) + Velocity (wheel) Control

# Order: left shoulder, right shoulder, left wheel, right wheel
robot.do_action([0.1, 0.2, 0.3, 0.4])

Torque Control

Please make sure to follow the argument order for the do_action method.

Index 0: Left joint motor position (rad) control

Index 1: Right joint motor position (rad) control

Index 2: Left wheel motor velocity (rad/s) control

Index 3: Right wheel motor velocity (rad/s) control

*When torque_ctrl=True, torque control is used for those motors

---

estop(msg: str = "", verbose: bool = True) -> None

Executes an emergency stop.

estop Example

robot.estop("Emergency")

Raises

• RobotEStopError

---

get_gains() -> dict

Returns the current gain settings.

get_gains Example

gains = robot.get_gains()
print(gains)  # {"kp": [...], "kd": [...]}

---

class flamingo_light_sdk.RL()

class RL()

Manages the reinforcement learning policy, builds the neural network input state from obs and cmd, and selects actions.

Quickstart

Basic RL Usage

from flamingo_light_sdk import *

rl = RL()
rl.add_mode(mode)                     # Add a mode
rl.set_mode(mode_id=1)                # Set the active mode
state = rl.build_state(obs, cmd)      # Build state
action = rl.select_action(state)      # Select action

Flow

---

add_mode(mode: Mode) -> None

Adds a mode. (Supports multiple modes)

---

set_mode(mode_id: int | None = None) -> None

Sets the mode to activate.

Parameters

• mode_id (int): Mode ID

---

build_state(obs: dict, cmd: dict, last_action: list[float] | None = None) -> list[float]

Converts observations into the neural network input (state) format.

Parameters

• obs (dict): Return value of robot.get_obs()

• cmd (dict): Return value of joystick.get_cmd()

• last_action (list[float] | None): User-provided last_action clipped to [-1,1] (optional)

If you do not pass last_action as an argument, RL stores and uses last_action internally (recommended).

build_state Example

state = rl.build_state(obs, cmd)
state = rl.build_state(obs, cmd, last_action=[0, 0, 0, 0])  # Specify manually if needed

Returns

• list[float]: 1D state vector

---

select_action(state: list[float]) -> list[float]

Runs the policy to generate an action.

select_action Example

action = rl.select_action(state)

---

class flamingo_light_sdk.Mode(mode_cfg: dict)

class Mode(mode_cfg: dict)

Defines per-mode policy settings. (Includes observation stack/scale and policy file path)

Basic Example

Mode Configuration Example

mode = Mode(mode_cfg={
    "id": 1,
    "stacked_obs_order": ["dof_pos", "dof_vel", "ang_vel"],
    "non_stacked_obs_order": ["command"],
    "obs_scale": {"dof_vel": 0.15, "command": 2.0},
    "action_scale": 0.5,
    "stack_size": 3,
    "policy_path": "weights/model.onnx",
    "cmd_vector_length": 4,
})

state Structure

mode_cfg keys

Key	Type	Default	Description
id	int	(Required)	Mode ID (1~16)
policy_path	str	(Required)	Path to the ONNX policy file
stacked_obs_order	list[str]	[]	List of observation keys to stack
non_stacked_obs_order	list[str]	[]	List of observation keys not to stack
obs_scale	dict	{}	Per-observation scale (scalar or vector)
action_scale	float | list[float]	1.0	Action scale
stack_size	int	1	Number of stacked frames
policy_type	str	"mlp"	"mlp" / "lstm"
cmd_vector_length	int	0	Command vector dimension
extra_obs	dict[str,int]	{}	Custom observations (key: name, value: dimension)

---

Default Observations

Key	Description	Dimension
dof_pos	Motor angle (rad)	2
dof_vel	Motor velocity (rad/s)	4
ang_vel	Angular velocity (wx, wy, wz) (rad/s)	3
proj_grav	Projected gravity vector (gx, gy, gz)	3
last_action	Previous-step action output	4
command	Joystick command vector	cmd_vector_length

---

Attributes (read-only)

• id: int

• stack_size: int

• state_length: int

• action_length: int

• policy_type: str

• policy_path: str

• stacked_obs_order: list[str]

• non_stacked_obs_order: list[str]

• action_scale: list[float]

• obs_scale: dict

• obs_lengths: dict

• cmd_vector_length: int

---

inference(state: list[float]) -> list[float]

Directly performs ONNX policy inference.

inference Example

action = mode.inference(state)

---

class flamingo_light_sdk.Joystick(max_cmd: list[float]=[], smoothness: float=50.0, mapping: dict={})

class Joystick(max_cmd=[], smoothness=50.0, mapping={})

Processes joystick input and returns cmd.

Quickstart

Basic Joystick Usage

joystick = Joystick()
cmd = joystick.get_cmd()

How to Connect

Parameters

• max_cmd (list[float], optional)

  • Limits each axis output range to [-max_cmd[i], +max_cmd[i]].

  • If the list length is shorter than 6, the remaining values are filled with 1.0.

  • To disable a specific axis, set that index to 0.

max_cmd Example (Use Only Some Axes)

# Use only indices 0 and 2; disable the rest
joystick = Joystick(max_cmd=[1.0, 0.0, 0.5, 0.0])
# → cmd_vector[0]: -1.0 ~ +1.0
# → cmd_vector[1]: always 0
# → cmd_vector[2]: -0.5 ~ +0.5
# → cmd_vector[3]: always 0
# → cmd_vector[4], [5]: -1.0 ~ +1.0 (default range)

• smoothness (float, optional) Applies a filter to joystick input. The larger the value, the smoother the output, but the slower the input response.

Fast Response

smoothness=10

joystick = Joystick(max_cmd=[1, 0, 1, 0], smoothness=10.0)

Smooth Movement

• mapping (dict[str,int], optional) You can map axes and buttons to specific indices of the command vector.

Default Mapping

Key Name	Command Index	Description	Value Range
LEFT_X	1	Left stick X-axis (left/right)	Continuous
LEFT_Y	0	Left stick Y-axis (up/down)	Continuous
RIGHT_X	2	Right stick X-axis (left/right)	Continuous
RIGHT_Y	3	Right stick Y-axis (up/down)	Continuous
LEFT_BTN	4	Left button (LB)	0 or 1
RIGHT_BTN	5	Right button (RB)	0 or 1

LEFT_BTN / RIGHT_BTN return a discrete value: 0 when not pressed, 1 when pressed.

Custom Mapping Example

# Example: change forward/backward movement to the right stick
custom_mapping = {
    "LEFT_X": 2,
    "LEFT_Y": 3,
    "RIGHT_X": 1,
    "RIGHT_Y": 0,   # forward/backward movement
    "LEFT_BTN": 4,
    "RIGHT_BTN": 5,
}

joystick = Joystick(mapping=custom_mapping)

Mapping Rules

• You must specify all 6 required keys (LEFT_X, LEFT_Y, RIGHT_X, RIGHT_Y, LEFT_BTN, RIGHT_BTN).

• Each index must be unique within the 0~5 range.

• If there are duplicate indices or missing keys, an invalid_argument exception is raised.

---

Mode Switching (mode_id)

Select mode_id(1~16) using a combination of the D-pad (⬆️➡️⬇️⬅️) and the face buttons (Y/B/A/X) combination. How to operate: While holding a D-pad direction, press one of Y/B/A/X at the same time.

D-pad Direction	Y	B	A	X
⬆️ Up	1	2	3	4
➡️ Right	5	6	7	8
⬇️ Down	9	10	11	12
⬅️ Left	13	14	15	16

---

Emergency Stop (E-Stop)

Function	Input Method
Emergency Stop (E-Stop)	Press LT + RT buttons simultaneously

During an emergency stop (E-Stop), all motors stop immediately.

---

get_cmd() -> dict

Returns joystick commands and status.

Returns

• cmd_vector (list[float]): Command vector

• mode_id (int | None): Current mode ID

• estop (bool): Whether E-Stop input is detected

get_cmd Return Example

cmd = joystick.get_cmd()
# {"cmd_vector": [...], "mode_id": 1, "estop": False}

---

is_connected() -> bool

Checks the joystick connection status.

is_connected Example

if joystick.is_connected():
    print("Connected")

---

function flamingo_light_sdk.control_rate(robot: Robot, hz: float = 50.0)

A decorator that runs the control loop at the specified Hz.

control_rate Example

@control_rate(robot, hz=50)
def loop():
    # Control logic
    pass

loop()

---

flamingo_light_sdk.onnxpolicy

class flamingo_light_sdk.onnxpolicy.MLPPolicy(weightPath: str)

class MLPPolicy(weightPath: str)

An ONNX-based MLP policy inference engine.

Parameters

• weightPath (str): Path to the ONNX model file

Methods

inference(state: list[float]) -> list[float]

Performs 1-step inference. state must be 1D.

The returned action is clipped internally to the [-1, 1] range.

---

class flamingo_light_sdk.onnxpolicy.LSTMPolicy(weightPath: str)

class LSTMPolicy(weightPath: str)

An ONNX-based LSTM policy (with state retention) inference engine.

Parameters

• weightPath (str): Path to the ONNX model file

Methods

inference(state: list[float]) -> list[float]

Performs 1-step inference (including internal h/c updates). state must be 1D.

---

5. Example Code

Example 1: Observation Check Test

example1.py

from flamingo_light_sdk import *

# Robot's Gains
kp = [15, 15, 0, 0]
kd = [0.45, 0.45, 0.3, 0.3]

# Instances
robot = Robot()

# Set gains
robot.set_gains(kp=kp, kd=kd)

# Get and print observation
obs = robot.get_obs()
print(obs)

# Send zero action
action = [0, 0, 0, 0]
robot.do_action(action)

Example 2: Joystick Test

Example 3: Control Using the RL Class

---

6. Applications

6.1 Switching Between Multiple Modes

Switching between multiple policies is supported. If build_state() detects mode_id in cmd, it can automatically switch modes.

multi_mode.py (Conceptual Example)

from flamingo_light_sdk import *

walk_mode = Mode(mode_cfg={"id": 1, "policy_path": "weights/walk.onnx", ...})
run_mode  = Mode(mode_cfg={"id": 2, "policy_path": "weights/run.onnx",  ...})

rl = RL()
rl.add_mode(walk_mode)
rl.add_mode(run_mode)
rl.set_mode(mode_id=1)  # Set initial mode

@control_rate(robot, hz=50)
def loop():
    obs = robot.get_obs()
    cmd = joystick.get_cmd()

    # Automatically switch modes when mode_id changes in cmd
    state = rl.build_state(obs, cmd)
    action = rl.select_action(state)
    robot.do_action(action)

loop()

---

6.2 Customizing Observations

You can process sensor data to create new observations and add them to the policy input. Define the dimensions of custom observations in advance with extra_obs, then add the data to the obs dictionary inside the loop.

example4.py (Conceptual Example)

from flamingo_light_sdk import *

# Robot's Gains
kp = [15, 15, 0, 0]
kd = [0.45, 0.45, 0.3, 0.3]

# RL mode with extra observations
mode = Mode(mode_cfg={
    "id": 1,
    "extra_obs": {
        "extra1": 4,   # 4D custom observation
        "extra2": 8,   # 8D custom observation
    },
    "stacked_obs_order": ["dof_pos", "dof_vel", "ang_vel", "proj_grav", "last_action", "extra1"],
    "non_stacked_obs_order": ["extra2"],
    "obs_scale": {"dof_vel": 0.15,
                  "ang_vel": 0.25,
                  },
    "action_scale": [0.85, 0.85, 40.0, 40.0],
    "stack_size": 3,
    "policy_path": "your_policy.onnx",
    "cmd_vector_length": 0,  # Do not use joystick commands
})

# Instances
robot = Robot()
rl = RL()

# Set gains
robot.set_gains(kp=kp, kd=kd)

# Add & Set Mode
rl.add_mode(mode)
rl.set_mode(mode_id=1)


@control_rate(robot, hz=50)
def loop():
    obs = robot.get_obs()                   # Get robot observation
    obs['extra1'] = GetCustomObs()          # Add extra observation 1 (1D list or np.ndarray)
    obs['extra2'] = GetLatentVector()       # Add extra observation 2 (1D list or np.ndarray)

    cmd = {"cmd_vector": None, "mode_id": None, "estop": False}
    state = rl.build_state(obs, cmd)        # Build state with extra obs
    action = rl.select_action(state)        # Select action
    robot.do_action(action)                 # Execute action

loop()

Extra observations must be in the form of a 1D list or a 1D np.ndarray.

---

6.3 Torque Control

Use torque control mode instead of position/velocity control.

torque_ctrl.py

@control_rate(robot, hz=50)
def loop():
    obs = robot.get_obs()
    cmd = joystick.get_cmd()
    state = rl.build_state(obs, cmd)
    action = rl.select_action(state)
    robot.do_action(action, torque_ctrl=True)  # Torque control mode

---

6.4 Scale Settings

How to apply scales to observations and actions.

Single Scalar

Applies the same scale to all elements.

"obs_scale": {"dof_vel": 0.15}  # All 4 elements × 0.15

Vector Scale

---

7. SDK Update

This requires an internet connection. After connecting via SSH, proceed in the following order.

Update

# 1. Enable Wi-Fi
sudo nmcli radio wifi on

# 2. Scan nearby networks
sudo nmcli dev wifi list

# 3. Connect to a network
sudo nmcli dev wifi connect "<SSID>" password "<PASSWORD>"

# 4. Update to the latest SDK
pip install -U flamingo-light-sdk

# 5. Disable Wi-Fi
sudo nmcli radio wifi off

---