FlmainGO-Light Python SDK [한국어]

1. 시작하기

1.1 SSH 접속

로봇의 전원을 켜면 Wi-Fi 핫스팟이 자동으로 활성화됩니다. 활성화된 Wi-Fi를 통해 로봇에 접속할 수 있습니다.

SSID	COCELO_ROBOT_XXXX
비밀번호	00000000

XXXX는 각 로봇마다 고유한 4자리 영문/숫자 조합 태그입니다.

SSH 접속

# 1) Wi-Fi 연결 (COCELO_ROBOT_XXXX 네트워크에 연결)
# 2) SSH 접속
ssh cocelo@XXXX    # XXXX = Wi-Fi SSID와 동일한 태그
                   # 비밀번호: 00000000

---

1.2 로봇 움직여보기

조이스틱 연결

1. 조이스틱의 중앙 홈버튼을 5초 이상 길게 누릅니다.

2. 페어링이 완료될 때까지 대기합니다.

조이스틱이 연결되지 않으면 100% 완충 후 다시 시도하세요.

로봇 깨우기/조종

로봇 깨우기

cocelo run example

• 컨트롤러의 왼쪽 스틱으로 로봇 이동을 제어합니다.

• 종료: Ctrl + C

종료 시 모터가 즉시 정지합니다. 반드시 손잡이를 잡고 로봇을 지지한 상태에서 종료하세요.

---

1.3 실행 로그 보기

명령어	설명
cocelo log list	저장된 로그 파일 목록 보기
cocelo log show last	가장 최근 로그 보기
cocelo log show <파일명>	특정 로그 파일 보기

로그 명령 예시

cocelo log list
cocelo log show last
cocelo log show <파일명>

---

2. SDK 미리 보기

아래 예제는 SDK의 핵심 사용 흐름을 보여줍니다.

play.py

from flamingo_light_sdk import *

# 1) 로봇 게인 설정
kp = [15, 15, 0, 0]
kd = [0.45, 0.45, 0.3, 0.3]

# 2) RL 모드 정의 (정책 및 관측 설정)
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) 인스턴스 생성
robot = Robot()
joystick = Joystick(max_cmd=[0.5, 0, 1, 0])
rl = RL()

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

# 5) 제어 루프 (50Hz)
@control_rate(robot, hz=50)
def loop():
    obs = robot.get_obs()              # 센서 데이터 획득
    cmd = joystick.get_cmd()           # 조이스틱 명령 획득
    state = rl.build_state(obs, cmd)   # 추론을 위한 state 구성
    action = rl.select_action(state)   # 정책 추론
    robot.do_action(action)            # 모터 명령 전송

loop()

제어 루프 순서: get_obs() → get_cmd() → build_state() → select_action() → do_action()

---

3. 패키지 구조

핵심 컴포넌트

컴포넌트	역할
Robot	로봇 인터페이스
Joystick	조이스틱 입력을 cmd 형태로 제공
Mode	정책(.onnx) + 관측/스케일/스택 설정
RL	네트워크 입력 state 구성 + 액션 선택
control_rate	제어 루프를 지정 주기로 실행

---

4. API 레퍼런스

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()

하드웨어 인터페이스를 제어합니다. 센서 관측을 읽고, 모터 명령을 전송합니다.

Quickstart

Robot 기본 사용

from flamingo_light_sdk import *

robot = Robot()                       # Robot 인스턴스 생성
robot.set_gains(kp=[...], kd=[...])   # PD 게인 설정
obs = robot.get_obs()                 # 센서 데이터 획득
robot.do_action([0, 0, 0, 0])         # 모터 명령 전송
robot.estop()                         # 긴급 정지

Attributes

gains_set: bool

게인 설정 여부입니다.

---

Robot()

로봇 인스턴스를 생성합니다.

Raises

• RobotInitError: 초기화 실패

---

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

4개 모터의 PD 게인을 설정합니다.

Parameters

• kp (list[float]): 비례 게인 (길이 4)

• kd (list[float]): 미분 게인 (길이 4)

set_gains 예시 순서: 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)

kp / kd 리스트에 들어가는 게인에 해당하는 모터의 순서는 반드시 아래와 일치해야 합니다.

인덱스 0: 왼쪽 관절 모터

인덱스 1: 오른쪽 관절 모터

인덱스 2: 왼쪽 바퀴 모터

인덱스 3: 오른쪽 바퀴 모터

Raises

• RobotSetGainsError

---

get_obs() -> dict

현재 센서 데이터를 반환합니다.

get_obs 예시

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

---

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

모터 명령을 전송합니다.

Parameters

• action (list[float]): 4개 모터 목표값(또는 토크값)

• torque_ctrl (bool, optional): True면 토크 제어 모드

기본 제어

위치(shoulder) + 속도(wheel) 제어 순서: left shoulder, right shoulder, left wheel, right wheel

robot.do_action([0.1, 0.2, 0.3, 0.4])

토크 제어

do_action 메소드의 인자의 순서를 반드시 지켜주세요.

인덱스 0: 왼쪽 관절 모터 위치 (rad) 제어

인덱스 1: 오른쪽 관절 모터 위치 (rad) 제어

인덱스 2: 왼쪽 바퀴 모터 속도 (rad/s) 제어

인덱스 3: 오른쪽 바퀴 모터 속도 (rad/s) 제어

*torque_ctrl=True 시, 해당 모터 토크 제어

---

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

긴급 정지를 실행합니다.

estop 예시

robot.estop("Emergency")

Raises

• RobotEStopError

---

get_gains() -> dict

현재 게인 설정을 반환합니다.

get_gains 예시

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

---

class flamingo_light_sdk.RL()

class RL()

강화학습 정책을 관리하고, obs와 cmd를 신경망 입력 state로 구성하며, 액션을 선택합니다.

Quickstart

RL 기본 사용

from flamingo_light_sdk import *

rl = RL()
rl.add_mode(mode)                     # 모드 추가
rl.set_mode(mode_id=1)                # 활성 모드 설정
state = rl.build_state(obs, cmd)      # state 구성
action = rl.select_action(state)      # 액션 선택

흐름

---

add_mode(mode: Mode) -> None

모드를 추가합니다. (다중 모드 지원)

---

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

활성화할 모드를 설정합니다.

Parameters

• mode_id (int): 모드 ID

---

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

관측값을 신경망 입력(state) 형태로 변환합니다.

Parameters

• obs (dict): robot.get_obs() 반환값

• cmd (dict): joystick.get_cmd() 반환값

• last_action (list[float] | None): 사용자가 직접 넣는 [-1,1]범위로 clip된 last_action (선택)

last_action을 인자로 주지 않으면, RL이 내부적으로 last_action을 저장하여 사용합니다 (권장).

build_state 예시

state = rl.build_state(obs, cmd)
state = rl.build_state(obs, cmd, last_action=[0, 0, 0, 0])  # 필요 시 직접 지정

Returns

• list[float]: 1D state 벡터

---

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

정책을 실행하여 액션을 생성합니다.

select_action 예시

action = rl.select_action(state)

---

class flamingo_light_sdk.Mode(mode_cfg: dict)

class Mode(mode_cfg: dict)

모드별 정책 설정을 정의합니다. (관측 스택/스케일/정책 파일 경로 포함)

기본 예시

Mode 구성 예시

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 구조

mode_cfg keys

키	타입	기본값	설명
id	int	(필수)	모드 ID (1~16)
policy_path	str	(필수)	ONNX 정책 파일 경로
stacked_obs_order	list[str]	[]	스택할 관측 키 목록
non_stacked_obs_order	list[str]	[]	스택하지 않을 관측 키 목록
obs_scale	dict	{}	관측치별 스케일 (스칼라 또는 벡터)
action_scale	float | list[float]	1.0	액션 스케일
stack_size	int	1	스택 프레임 수
policy_type	str	"mlp"	"mlp" / "lstm"
cmd_vector_length	int	0	명령 벡터 차원
extra_obs	dict[str,int]	{}	사용자 정의 관측치 (키: 이름, 값: 차원)

---

기본 관측값

키	설명	길이 (차원)
dof_pos	모터 각도 (rad)	2
dof_vel	모터 속도 (rad/s)	4
ang_vel	각속도 (wx, wy, wz) (rad/s)	3
proj_grav	투영 중력 벡터 (gx, gy, gz)	3
last_action	이전 스텝 액션 출력	4
command	조이스틱 명령 벡터	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]

ONNX 정책 추론을 직접 수행합니다.

inference 예시

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={})

조이스틱 입력을 처리하여 cmd를 반환합니다.

Quickstart

Joystick 기본 사용

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

연결 방법

Parameters

• max_cmd (list[float], optional)

  • 각 축 출력 범위를 [-max_cmd[i], +max_cmd[i]]로 제한합니다.

  • 인자리스트 길이가 6보다 짧으면 나머지는 1.0으로 채워집니다.

  • 특정 축을 비활성화하려면 해당 인덱스를 0으로 설정합니다.

max_cmd 예시 (축 일부만 사용)

# 인덱스 0, 2만 사용, 나머지 비활성화
joystick = Joystick(max_cmd=[1.0, 0.0, 0.5, 0.0])
# → cmd_vector[0]: -1.0 ~ +1.0
# → cmd_vector[1]: 항상 0
# → cmd_vector[2]: -0.5 ~ +0.5
# → cmd_vector[3]: 항상 0
# → cmd_vector[4], [5]: -1.0 ~ +1.0 (기본 범위)

• smoothness (float, optional) 조이스틱 입력에 필터를 적용합니다. 값이 클수록 출력이 부드럽지만, 입력 반응이 느려집니다.

빠른 반응

smoothness=10

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

부드러운 움직임

• mapping (dict[str,int], optional) 축(axis)과 버튼을 명령 벡터의 특정 인덱스에 매핑할 수 있습니다.

기본 매핑 (Default Mapping)

키 이름	명령 인덱스	설명	값 범위
LEFT_X	1	왼쪽 스틱 X축 (좌우)	연속
LEFT_Y	0	왼쪽 스틱 Y축 (상하)	연속
RIGHT_X	2	오른쪽 스틱 X축 (좌우)	연속
RIGHT_Y	3	오른쪽 스틱 Y축 (상하)	연속
LEFT_BTN	4	왼쪽 버튼 (LB)	0 또는 1
RIGHT_BTN	5	오른쪽 버튼 (RB)	0 또는 1

LEFT_BTN / RIGHT_BTN은 누르지 않으면 0, 누르면 1의 불연속 값을 반환합니다.

커스텀 매핑 예시

# 예: 전후 이동을 오른쪽 스틱으로 변경
custom_mapping = {
    "LEFT_X": 2,
    "LEFT_Y": 3,
    "RIGHT_X": 1,
    "RIGHT_Y": 0,   # 전후 이동
    "LEFT_BTN": 4,
    "RIGHT_BTN": 5,
}

joystick = Joystick(mapping=custom_mapping)

매핑 규칙

• 6개의 필수 키(LEFT_X, LEFT_Y, RIGHT_X, RIGHT_Y, LEFT_BTN, RIGHT_BTN)를 모두 지정해야 합니다.

• 각 인덱스는 0~5 범위 내에서 고유해야 합니다.

• 중복 인덱스나 누락된 키가 있으면 invalid_argument 예외가 발생합니다.

---

모드 전환 (mode_id)

D-pad(⬆️➡️⬇️⬅️)와 페이스 버튼(Y/B/A/X) 조합으로 mode_id(1~16)를 선택합니다. 조작 방법: D-pad 방향을 누른 상태에서 Y/B/A/X 중 하나를 동시에 누릅니다.

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

---

긴급 정지 (E-Stop)

기능	입력 방식
긴급 정지 (E-Stop)	LT + RT 버튼 동시 누름

긴급 정지(E-Stop) 시 모든 모터가 즉시 정지합니다.

---

get_cmd() -> dict

조이스틱 명령 및 상태를 반환합니다.

Returns

• cmd_vector (list[float]): 명령 벡터

• mode_id (int | None): 현재 모드 ID

• estop (bool): E-Stop 입력 감지 여부

get_cmd 반환 예시

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

---

is_connected() -> bool

조이스틱 연결 상태를 확인합니다.

is_connected 예시

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

---

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

지정된 Hz로 제어 루프를 실행하는 데코레이터입니다.

control_rate 예시

@control_rate(robot, hz=50)
def loop():
    # 제어 로직
    pass

loop()

---

flamingo_light_sdk.onnxpolicy

class flamingo_light_sdk.onnxpolicy.MLPPolicy(weightPath: str)

class MLPPolicy(weightPath: str)

ONNX 기반 MLP 정책 추론기입니다.

Parameters

• weightPath (str): ONNX 모델 파일 경로

Methods

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

1-step 추론을 수행합니다. state는 반드시 1D여야 합니다.

반환 액션은 내부에서 [-1, 1] 범위로 클립됩니다.

---

class flamingo_light_sdk.onnxpolicy.LSTMPolicy(weightPath: str)

class LSTMPolicy(weightPath: str)

ONNX 기반 LSTM 정책(상태 보존) 추론기입니다.

Parameters

• weightPath (str): ONNX 모델 파일 경로

Methods

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

1-step 추론(내부 h/c 업데이트 포함). state는 반드시 1D여야 합니다.

---

5. 예제 코드

예제 1: 관측치 확인 테스트

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)

예제 2: 조이스틱 테스트

예제 3: RL 클래스를 활용한 제어

---

6. 응용

6.1 다중 모드 전환

여러 정책 간 전환을 지원합니다. build_state()가 cmd에서 mode_id를 감지하면 자동으로 모드를 전환할 수 있습니다.

multi_mode.py (개념 예시)

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)      # 초기 모드 설정

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

    # cmd 내 mode_id 변경 시 자동으로 모드 전환
    state = rl.build_state(obs, cmd)
    action = rl.select_action(state)
    robot.do_action(action)

loop()

---

6.2 관찰값 커스터마이징

센서 데이터를 가공하여 새로운 관측치를 만든 후 정책입력에 추가할 수 있습니다. extra_obs로 커스텀 관측치의 차원을 미리 정의하고, 루프 내에서 obs 딕셔너리에 데이터를 추가합니다.

example4.py (개념 예시)

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,   # 4차원 커스텀 관측치
        "extra2": 8,   # 8차원 커스텀 관측치
    },
    "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,  # 조이스틱 명령 미사용
})

# 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 observation은 반드시 1D list 또는 1D np.ndarray 형태여야 합니다.

---

6.3 토크 제어

위치/속도 제어 대신 토크 제어 모드를 사용합니다.

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)  # 토크 제어 모드

---

6.4 스케일 설정

관측값 및 액션에 스케일을 적용하는 방법입니다.

단일 스칼라

모든 요소에 동일한 스케일을 적용합니다.

"obs_scale": {"dof_vel": 0.15}  # 4개 요소 모두 × 0.15

벡터 스케일

---

7. SDK 업데이트

인터넷 연결이 필요한 작업입니다. SSH 접속 후 아래 순서대로 진행하세요.

Update

# 1. Wi-Fi 활성화
sudo nmcli radio wifi on

# 2. 주변 네트워크 검색
sudo nmcli dev wifi list

# 3. 네트워크 연결
sudo nmcli dev wifi connect "네트워크이름" password "비밀번호"

# 4. 최신 SDK 업데이트
pip install -U flamingo-light-sdk

# 5. Wi-Fi 비활성화
sudo nmcli radio wifi off

---