FlaminGO- Python SDK

FlmainGO 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.

Motor set zero

Run Example

cd fx_client/example
python req_test.py

Make sure that emergency stop is not pressed.

• Press a in the terminal to get the motor state. Make sure all the state is set to "2" after pressing a then go to the next step.

• Press z in the terminal to send all motor to zero position.

• Robot will go the the standing position after pressing z.

• Press q in the terminal to quit the motor set-zero mode.

Make sure to press q and go to the Wake/Control step.

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_sdk import *

# 1) Robot gain settings
kp = [70.0, 70.0, 70.0, 70.0, 70.0, 70.0, 0.0, 0.0]
kd = [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.7, 0.7]

# 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.05,
        "ang_vel": 0.25,
        "command": [2.0, 0.0, 0.25, 0.0],
    },
    "action_scale": [0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 40.0, 40.0],
    "stack_size": 3,
    "policy_path": "your_policy.onnx",
    "cmd_vector_length": 4,
})

# 3) Create instances
robot = Robot()
mapping = [
    "LEFT_Y",                   # cmd[0]
    "BTN_THUMBL",               # cmd[1]
    "LEFT_X",                   # cmd[2]
    "BTN_A:-0.4,BTN_Y:0.4",     # cmd[3]
]
joystick = Joystick(mapping=mapping, max_cmd=[(-1.0, 1.0), (-0.0, 0.0), (-1.5, 1.5), (-0.0, 0.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_sdk

• Robot

• Joystick

• Mode

• ModeConfig

• RL

• control_rate

flamingo_sdk.onnxpolicy

• MLPPolicy

• LSTMPolicy

Exceptions

• RobotInitError

• RobotSetGainsError

• RobotEStopError

• ModeConfigError

---

flamingo_sdk

class flamingo_sdk.Robot()

class Robot()

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

Quickstart

Basic Robot Usage

from flamingo_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, 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 8 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 hip, right hip, left shoulder, right shoulder, left_leg, right_leg, left_wheel, right_wheel

kp = [70.0, 70.0, 70.0, 70.0, 70.0, 70.0, 0.0, 0.0]
kd = [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.7, 0.7]

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 hip motor

Index 1: Right hip motor

Index 2: Left shoulder motor

Index 3: Right shoulder motor

Index 4: Left leg motor

Index 5: Right leg motor

Index 6: Left wheel motor

Index 7: 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 hip, right hip, left shoulder, right shoulder, left leg, right leg, left wheel, right wheel
robot.do_action([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8])

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 joint motor position (rad) control

Index 3: Right joint motor position (rad) control

Index 4: Left joint motor position (rad) control

Index 5: Right joint motor position (rad) control

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

Index 7: 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_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_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, 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_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.05, "command": 2.0},
    "action_scale": [0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 40.0, 40.0],
    "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]	0.25	Action scale
stack_size	int	3	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_sdk.Joystick(max_cmd: list[pair(double, double)]=[], 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[pair(double, double)], optional)

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

  • If the argument list length is shorter than cmd_vector_length, the remaining values are filled with (-1.0, 1.0).

  • To disable a specific axis, set the corresponding index to (-0.0, 0.0).

max_cmd Example (Use Only Some Axes)

# Use only indices 0 and 2; disable the rest
joystick = Joystick(max_cmd=[(-1.0, 1.0), (-0.0, 0.0), (-0.5, 0.5), (-0.0, 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]: not use // length of cmd_vector is 4

• 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), (0.0, 0.0), (-1.0, 1.0), (0.0, 0.0)], smoothness=10.0)

Smooth Movement

• mapping(str) : Maps buttons to the command vector in order. For discrete buttons, the delta value can also be specified.

Mapping Example

custom_mapping = {
    "LEFT_Y",                   # cmd[0]
    "BTN_THUMBL",               # cmd[1]
    "LEFT_X",                   # cmd[2]
    "BTN_A:-0.5,BTN_Y:0.4",     # cmd[3], amount of change must be specified(decrease -0.5, increase 0.4)
}

joystick = Joystick(mapping=custom_mapping)

Mapping Rules

• Users must map the same number of buttons as the cmd_vector_length defined in the mode.

• Each button must be uniquely mapped, and for discrete buttons such as BTN_A, BTN_B, BTN_Y, and BTN_X, both increase and decrease deltas must be defined.

---

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_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_sdk.onnxpolicy

class flamingo_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.

---

class flamingo_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_sdk import *

# Robot's Gains
kp = [70.0, 70.0, 70.0, 70.0, 70.0, 70.0, 0.0, 0.0]
kd = [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.7, 0.7]

# 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, 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_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_sdk import *

# Robot's Gains
kp = [70.0, 70.0, 70.0, 70.0, 70.0, 70.0, 0.0, 0.0]
kd = [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.7, 0.7]

# 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.05,
                  "ang_vel": 0.25,
                  },
    "action_scale": [0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 40.0, 40.0],
    "stack_size": 3,
    "policy_path": "your_policy.onnx",
    "cmd_vector_length": 0,  # Do not use joystick commands
})

# Instances
robot = Robot()
mapping = [
    "LEFT_Y",                   # cmd[0]
    "BTN_THUMBL",               # cmd[1]
    "LEFT_X",                   # cmd[2]
    "BTN_A:-0.4,BTN_Y:0.4",     # cmd[3]
]
joystick = Joystick(mapping=mapping, max_cmd=[(-1.0, 1.0), (-0.0, 0.0), (-1.5, 1.5), (-0.0, 0.0)])
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.05}  # All 4 elements × 0.05

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

---