Skip to main content

N2 Comprehensive Usage Document

I. About the N2​


(I) Component Information​

info

The N2 robot has 18 degrees of freedom (DOF) in total. Each arm has 4 DOF, including (left-handed coordinate system):

  1. Left-arm shoulder joint — pitch axis

  2. Left-arm shoulder joint — roll axis

  3. Left-arm elbow joint — yaw axis

  4. Left-arm elbow joint — pitch axis

Each leg has 5 DOF, including:

  1. Left-leg hip joint — yaw axis

  2. Left-leg hip joint — roll axis

  3. Left-leg thigh joint — pitch axis

  4. Left-leg knee joint — pitch axis

  5. Left-leg ankle joint — pitch axis

Equipped with multiple joint motor degrees of freedom, the N2 robot is capable of precise motion control and posture control.

Details are as follows:

ParameterN2N2 EDU
Height, Width and Thickness (Standing)1140mm*491.38mm*280mm
Weight with batteryApprox 30kg
Total DOF18
DOF per leg5
DOF per arm4
Computing module/NVIDIA Jetson Orin Nano Super(67TOPS)
Joint communicationEthercat & Canfd
Max knee-joint torque150N.m
Thigh + shank lengthApprox. 0.76M
Arm spanApprox. 0.4M
Joint encodersDual encoders
End effectorsBall-type hands / stylized handsBall-type hands / stylized hands
Joint output bearingsCrossed Roller + Deep Groove BallCrossed Roller + Deep Groove Ball
Continuous walking load capacityApprox. 5 kg
Extra-large joint movement rangesKnee joint: 0~126°
Hip joint: P -90°~45°, R -37°~+ 57°, Y -37°~+ 57°
Power supplyLithium Battery
Base computing power6 Tops6+67 Tops
Perception sensorsIMU, Depth Camera
Microphone arrayOptional
5W speakerOptional
Smart batteryQuick-release battery
ChargerIncluded, 54.6V 5A
Aolion controllerIncluded
Battery life2~3H
Secondary development (HighController)SupportedSupported
Secondary development (LowController)/Supported
Component Introduction diagram
image.png

(II) Electrical Interfaces​

The following electrical interfaces are provided on the back of the N2:

背后接口.png

Serial No.TypeDescriptionQuantity
1RJ45Switch 1000 BASE-T1
2USBMotion control board USB 3.02
3HDMIMotion control board, HD Display Cable1

The HDMI port is wired to the motion control board (RK3588S). If you purchased the EDU version, the secondary-development compute board (NVIDIA Jetson Orin Nano Super) can currently be accessed only via SSH.

(III) Airborne Computer​

TypeModeluserPasswordIPcomputing powerFrequencyMemory
Motion control board鲁班猫 RK3588S
Not user-accessible192.168.55.1026 Tops2.4GHz8+64GB
Secondary development computing boardNVIDIA Jetson orin nano super
noetixn2192.168.55.10167 Tops1.7GHz8+128GB

The secondary-development computing board is available exclusively on the N2 EDU version.

danger

While the robot's motion control program is running, do not connect to the robot's motion control board (RK3588S) via SSH under any circumstances. An SSH connection may consume EtherCAT network bandwidth, potentially interrupting the motion control process and causing the robot to lose motor control and collapse to the ground, which may result in equipment damage or personal injury.

If an SSH connection is required, the robot must first be placed in a prone position on the ground or suspended on a protective support rack and switched to a disabled state. During the SSH connection process, ensure that there are no objects around the robot and that personnel maintain a safe distance from the robot to prevent collisions or other hazards caused by unexpected robot movements.

Our company shall not be held responsible for any equipment damage, personal injury, or other losses resulting from failure to follow the above SSH connection safety requirements.

danger

The Motion Control Board (鲁班猫 RK3588S) is not accessible to users. If the user accesses the Motion Control Board without authorization and this causes the robot’s motion control program to malfunction or lose control, our company shall not be responsible for any resulting damage or losses.

(IV) Camera Information​

Intel RealSense D435i Camera (Standard Configuration)

Intel® RealSense™ Depth Camera D435i - Product Specifications | Intel

(V) Battery Information​

ParameterInformation
BrandGrepow (Shenzhen Grepow Battery Co., Ltd.)
Model numberGRP4459160-13S1P
Capacity7500mAh
Voltage48V

II. Instructions for Use​


(I) Powering On and Precautions​

tip

It is recommended that you hang the N2 using a protective bracket throughout daily demonstrations, especially during secondary development, to better protect the N2 device.

danger

The factory's original motion control function does not currently support ascending or descending stairs. Please operate the N2 robot in a flat and open area, and keep it away from crowds to avoid injury from falls or damage to the robot.

tip

Initiate the process

Take the robot out of the packaging box. It is recommended to hang the robot on a rack for startup, or you may also start the robot while it is lying (prone) on the ground.

Install the battery

Installing the battery: Press and hold the silver latch button on the left side of the robot (press it all the way down), and push the battery inward at the same time to insert it into place.

(The same applies to removing the battery.)

pay attention to the battery orientation when installing it — the button must face up and the indicator lights must face down.

Install the controller receiver

Plug the USB receiver of the controller into any USB port on the back of the robot, and make sure it is connected securely without loose contact.

Power on the robot

After the battery is inserted into the robot's back, briefly press the power button on the battery; once the indicator lights up, press and hold the button. The battery indicators will then show a flowing-light effect, and after a single beep the indicator lights on all parts of the robot will light up, indicating that the robot is powered on.


Precautions

Factory Motion Control Modes

ModeFunctionRemarks (button assignments shown for the AOLION controller)
Disabled ModeAll joints of the robot go limpPressing + in any state enters Disabled Mode (emergency stop)
Enabled ModeAll joints of the robot provide dampingPress + while in Disabled Mode to enter Enabled Mode
Ready ModeThe limbs bend slightly, preparing for motionPress LB & - while in Enabled Mode to enter Ready Mode
Walking ModeThe robot can stand and walk autonomouslyPress LB & X in Ready/Running Mode to enter Walking Mode. Do not lift the robot's feet off the ground in this Mode, otherwise the robot will kick randomly and cause injury.
Running ModeThe robot can stand and run autonomouslyPress LB & Y while in Walking Mode to enter Running Mode. Do not lift the robot's feet off the ground in this Mode, otherwise the robot will kick randomly and cause injury.
Dance ModeThe robot enters the dance preparation modePress LB & A in Walking Mode to enter Dance mode. Do not lift the robot's feet off the ground in this mode, otherwise the robot will kick randomly and cause injury.
Teaching ModeThe robot enters the Teaching Mode and records the arm movementsPress RB & Y in Walking Mode to enter Teaching mode. Do not lift the robot's both feet off the ground in this mode, otherwise the robot will kick randomly and cause injury.

Use flowcharts

image.png

The black left-pointing arrows indicates the normal shutdown procedure

The black right-pointing arrows indicates the normal usage process

The red arrow indicates the emergency stop operation in case of emergency. Pressing the emergency stop (+ button) in any other mode will trigger the Disable Mode. Please take care to avoid accidental activation during use.

(II) Controller Pairing and Operation Control​

tip

Pair the controller

When Pairing the Controller and the receiver for the first time, make sure the robot is powered on and the controller receiver is plugged in, then press and hold the home button on the controller until the indicator light stays on steadily. Release the button at this point, and the indicator light will flash rapidly to enter pairing mode. When the controller vibrates and the three indicator lights below stay on steadily, the pairing is successful.

After the initial pairing has been completed, subsequent connections can be restored simply by briefly pressing the HOME button.

The following operations take the Aolion controller as an example

tip

Entering Walking Mode

After the robot is powered on, it will automatically enter the Enabled Mode (damping mode) after waiting for about 10 seconds.

After the robot enters the Enabled Mode, make the robot stand upright on the ground, press LB and - to let the robot enter the Ready Mode

Observe whether the robot's legs are slightly bent, and press LB and X to enter Walking Mode once this happens; if the legs do not bend, repeat the previous step

Note: The robot cannot climb stairs or obstacles higher than 5 cm, nor can it traverse slopes with an incline greater than 25 degrees (as there is a risk of tipping over).

For subsequent operations, please refer to the button function chart below

Controller Button Function Chart

  1. Basic Functions

image.png

ButtonPreconditionFunctionRemarks
+Enabled/Disabled ModeEnable and Disable
LB & -Enabled ModeReady ModeUnable to maintain balance independently at this point, requiring manual assistance to stay standing
LB & XReady ModeWalking ModeUse the joysticks to help maintain balance
LB & YWalking ModeRunning ModePlease reserve sufficient space and advance stopping distance
LB & BWalking ModeControlled fallAutomatically returns to Ready Mode after the fall
Left JoystickWalking/Running ModeMove forward and backward
Right JoystickWalking/Running ModeTurn left / right
AWalking ModeShake hands
BWalking ModeWave
YWalking ModeCheer
danger

The "+" button on the Aolion controller is used to enable/disable the robot, and can also function as an emergency stop for the robot in critical situations.

When the robot is operating normally, be careful not to press or accidentally touch the "+" key, otherwise the robot will immediately disable and fall to the ground, which may cause losses, so please avoid such a situation.

  1. Teaching Function
tip

The teaching function allows users to record motions by manually swinging the robot's dual arms. The system collects the angle and duration of each joint in real time, and saves the generated motion trajectory (. bin file) to the data directory of the RK3588S motion control board SDK. Subsequent playback can be triggered via the controller buttons or DDS Client, enabling the robot to accurately reproduce the recorded motion trajectory.

In short: Users can DIY dynamic hand poses for robots with zero coding.

image.png

ButtonPreconditionFunctionRemarks
RB & YWalking ModeEnter the teaching state
RB & BTeaching ModeEnd teaching
RB & XTeaching EndedSave the taught motionThen press [A, B, X, Y] to save it to the corresponding button
RB & LB & [A, B, X, Y]Walking ModePlay back the taught motion saved under the corresponding buttonAfter playback ends, always switch back to Walking Mode before playing another taught motion or switching to any other mode
  1. Dance Function (Currently only compatible with Aolion controllers)
caution

Please follow the points below when using the dance function:

  • Please reserve sufficient activity space as required in the remarks, and ensure the road surface is flat and non-slip.

  • The battery level is at 2 bars or above

  • Do not hold the robot tightly with force while dancing, and avoid subjecting it to external force interference.

  • For some dance moves, you can switch to Walking Mode to interrupt the animation when the character is nearly standing midway, but do not switch to Walking Mode while the character is performing a bending-down dance action.

PS: Please avoid using it on slippery or uneven ground. Ensure there is sufficient space for movements when using it for dance. Damage to the robot caused by the operating environment or operational error is not covered under the warranty.

If you need to test the Yingge dance after receiving the robot, a person must be present for protection during the first test: hold the tether (only for protection, do not apply additional force to the lifting rope), and reserve a sufficiently large demonstration space. This allows you to clearly understand the approximate required operating space before proceeding with subsequent demonstrations. If any issues arise during the first test, please contact customer service staff promptly.

ButtonPreconditionFunctionRemarks
LB & AWalking ModeEnter Dance ModePlease reserve a space of 6 * 6 (meters)
XDance ModePlay the full-length version of the Yingge DancePlease reserve a space of 6 * 6 (meters)
YDance ModePlay the short version of the Yingge DancePlease reserve a space of 6 * 6 (meters)
LT & YWalking ModePlay broadcast exercisePlease reserve a space of 6 * 6 (meters)
LT & AWalking ModePlay the Spring Festival dancePlease reserve a space of 6 * 6 (meters)
LT & BWalking ModePlay the cha-chaPlease reserve a space of 6 * 6 (meters)
  1. High-difficulty movements with significant amplitude
danger

Be sure to note the following 7 points when using the following functions:

  1. Use in an open area in accordance with the functional requirements, where the ground is flat without slope, rough and non-slip, and clear of surrounding clutter.

  2. Do not stay too far away from the machine during use, as this will cause the robot to disconnect and lose control!!!

  3. During the performance, stay within the area required by the function, and keep the performance area — especially the landing zone of the maneuver — far away from bystanders, particularly women and children.

  4. If the robot fails during the maneuver, immediately press the + button on the controller to disable the robot

  5. The battery indicator shows 4 bars

  6. Do not use it twice consecutively within half an hour

  7. The end effector of the robot must be the original factory-installed plastic ball hand.

If the product is not used in accordance with the above requirements, our company shall not be liable for any resulting losses.

ButtonPreconditionFunctionRemarks
LT & X
Walking Mode
Step-in cartwheel (the robot faces forward)Requires an open area with a 10 m clear semicircular zone extending ±90° to the left and right, centered on the robot's forward direction.

robot_operating_space_en.png

(III) Equipment Shutdown and Battery Charging​

caution

Shutdown Procedure

After use, hold the robot and press LB and - to return the robot to Ready Mode. At this point, the robot will lose the ability to stand on its own and requires manual support.

Lift the robot up or lay it flat (prone), then press the + key to put the robot into Disabled Mode

Then press and hold the motor switch, remove the battery after the unit shuts down, plug the battery charging adapter into a 220V power outlet, then insert the motor into the battery base — the battery's charging indicator will flash (no response if fully charged) — and finally store the N2 properly in a safe place.

(IV) Operation Tutorial Video​

III. N2 Development Guide​


tip

Introduction to SDK

This document describes N2 development based on the DDS messaging middleware. The SDK adopts a client/server (C/S) architecture: under an isolation mechanism, the DDS client program deployed on the robot's secondary-development computing board sends control commands at a rate of 500 Hz to the motion control program running on the motion control board, which acts as the server, and continuously retrieves the robot's current state. The DDS adopted is CYCLONEDDS 0.11.0.

caution

Only the N2 model equipped with a computing power board version can use this SDK for development

(I) System Architecture Diagram​

image.png

(II) Developing Interfaces​

DDS C++

(III) Obtaining the SDK​

https://github.com/Noetix-Robotics/noetix_sdk_n2

(IV) URDF Files​

N2_URDF.zip

(V) Application Development: Highcontrol​


tip

Introduction to Application Development

HighController is developed for upper-layer scheduling based on the OEM motion control strategy, which enables the rapid construction of robot automated applications without modifying the underlying control logic, supports integration with large language models (LLMs), and facilitates the creation of customized intelligent behavior systems.

Typical applications include:

  • Combining visual algorithms with the OEM motion control system to realize autonomous perception and autonomous navigation

  • Integrating with the voice interaction module to realize natural language control

  • Integrating with LLMs to dynamically generate and invoke original manufacturer's control actions based on inputs (this carries certain risks, requiring strict security policies)

  • Implementing a positioning and navigation inspection system in coordination with the External Perception Radar

Simply put, HighController encapsulates the original factory's control capabilities through high-level scheduling, enabling automated and programmatic invocation of the behaviors that are manually controllable via the remote controller or the mobile app, and on this basis, extends the system with a degree of autonomy and intelligence.

1.Highcontrol Architecture Diagram​

image.png

(1) Status reporting mechanism

After the Client SDK establishes a connection with the robot motion control program, the motion control program will continuously send real-time robot status information to the client, including:

  • Whole-body motor parameter data (pos: position, vel: velocity, tau: torque, kp, kd, temperature, error)

  • IMU status data

  • Current working mode (workmode, indicating the control policy currently running)

  • Aolion Controller Data (used to synchronize manual input or assist control)

  • Battery level and related system status information


(2) Client control command delivery

The client, based on its own application scenarios, sends control commands to the motion control program, which mainly include:

  • (x, y, z) movement control data valid only in specific modes, such as Walking Mode, Handshake, Wave, Cheer, and Teaching Mode.

  • action command corresponds to workmode, which is used to switch or trigger the algorithm strategy currently running on the robot.

  • data (additional DDS payload) typically used in PLAYTEACH (playback Teaching Mode), and is used to specify additional parameters such as the teaching file index.


(3) Internal processing flow of the motion control program

After receiving the client's command, the motion control program:

  • Transfers the control parameters to the internal control algorithm

  • The algorithm calculates the strategy based on the reinforcement learning model

  • Generates the target expected values (target position, velocity or torque) of the motor and send them to the motor control interface

  • Delivers the calculation results to the hardware control layer


(4) Hardware execution layer

After receiving the target control data, the hardware layer:

  • Executes the motor control commands

  • Performs the corresponding expected action


Throughout the entire process, users only need to issue a portion of high-level control parameters.

The specific motion planning, dynamic balance and motor-level control calculations are all completed by the black-box algorithms in the original manufacturer's motion control program.

Therefore, in HighController mode, the range of capabilities that users can invoke and automate is, in principle, limited to the functional boundaries originally achievable by the APP or the controller, without granting underlying motor-level control access.

2.Highcontrol Operation Flowchart​

image.png

(1) Initialization phase (init)

After the system is started, the following initialization process will be completed:

  1. Establish a communication connection between the client and the robot motion control program

  2. Register the callback function for receiving robot status data


(2) Status data callback mechanism

The motion control program continuously pushes robot status data to the client.

After receiving the data, the callback function encapsulates it and stores it in the buffer and the global state variable respectively:

  • motor_state_buffer_: Motor Status Buffer

  • imu_buffer_: IMU status buffer

  • joy_buffer_: Gamepad data buffer

  • curmode: Current motion control policy mode (global variable)

This stage is only responsible for data reception and caching, and does not perform control decision computations.

3.HighController Parameter Table and Common Interface Usage​

HighController Interfaces
Interface NameInterface DescriptionReturn Type
instanceObtain the singleton pointer of HighControllerobject pointer
initInitialize the HighController objectNone
publish_cmdIssue DDS control command dataNone
subscribe_robot_hardware_statusSubscribe to robot hardware status informationNone

Obtain the HighController Singleton

Function Nameinstance
Function Prototypestatic HighController *Instance()
Function OverviewObtain the HighController singleton
ParameterNone
Return ValuePointer to the HighController singleton object
Remarks

C++ Example:

HighController *ctrl = HighController::Instance();

Python Example:

ctrl = HighController.instance()

Initialize the HighController Object

Function Nameinit
Function Prototypebool init()
Function OverviewHighController Object Initialization
ParameterNone
Return Valuebool
Remarks

C++ Example:

ctrl->init();

Python Example:

ctrl.init()

Publish robot control commands

Function Namepublish_cmd
Function Prototypevoid publish_cmd(double ver, double hor, double yaw, ControlCmd action, uint16_t index)
Function OverviewUse HighController to send DDS control commands
Parameter- ver range: [-1,1]; longitudinal movement value of the robot (> 0: forward)
- hor range: [-1,1]; lateral translation value of the robot (> 0: leftward)
- Yaw range: [-1,1]; turning value of the robot (> 0: left turn)
- action: robot mode switching enumeration
- index: specified index for teaching-related modes
Return ValueNone
RemarksThis interface cannot be called continuously; otherwise, the robot will receive commands too fast to respond, and a delay of at least 2ms needs to be added after each command is sent.

C++ Example:

ctrl->publish_cmd(0, 0, 0, ControlCmd.CHEER, 0);

Python Example:

ctrl.publish_cmd(0, 0, 0, ControlCmd.CHEER, 0)

action The parameter indicates switching the robot to the corresponding mode

Parameter NameDefine PrototypeSerial No.Sample ValueDescription
ControlCmd
enum class ControlCmd : uint8_t {
WALK,
SWING,
SHAKE,
CHEER,
RUN,
START,
SWITCH,
STARTTEACH,
SAVETEACH,
ENDTEACH,
PLAYTEACH,
DANCE1,//YG L
DANCE2,//YG S
DANCE3,// QIAQIA
DANCE4,//TICAO
DANCE5,//216
CF,
TANG,
DEFAULT
};
0WALKWalking Mode
1SWINGFactory preset action: wave
2SHAKEFactory preset action: handshake
3CHEERFactory preset action: cheer
4RUNRunning Mode
5STARTEnable/Disable
6SWITCHReady Mode
7STARTTEACHStart teaching
8SAVETEACHSave the taught motion
9ENDTEACHEnd teaching (deprecated)
10PLAYTEACHPlay the taught motion
11DANCE1Yingge Dance (Long Form)
12DANCE2Yingge Dance (Short Form)
13DANCE3Cha-Cha
14DANCE4Broadcast exercise
15DANCE5Spring Festival dance
16CFCartwheel
17TANGControlled fall
18DEFAULTNo-op (idle)
danger

When using the DDS SDK to trigger the robot's cartwheel (see figure below) or the dances (6 m × 6 m), the robot must be kept far away from crowds, and a large, redundant open area must be reserved as required by each function. Otherwise, the company assumes no liability for any loss incurred!

Required space for the cartwheel

image.png

tip

Purpose of the DEFAULT (No-Op) Value

The robot's control thread executes the process control function cyclically. If commands such as action = ControlCmd::CHEER; (motion triggers or mode switches) are dispatched continuously inside that loop, the robot keeps receiving new CHEER commands before the cheer motion has finished, and the motion is interrupted over and over — the robot appears “stuck” or “unresponsive”.

Correct Practice

CHEERis a one-time trigger command (event) and shall only be sent once; afterward, continuously send DEFAULT (a no-op command) in the loop to prevent repeated triggering.

Sample Code (Revised)

if (is_first) {
action = ControlCmd::CHEER; // Triggered only once
is_first = false;
} else {
action = ControlCmd::DEFAULT;
}

Effect

  • Received CHEER→ Trigger and fully execute the cheer action

  • Subsequent DEFAULT → No longer interrupts the action

  • The robot behaves normally and predictably

Action commands shall be "edge-triggered" and must not be continuously issued within a control loop.

indexUsed to specify the teaching file index in teaching-related modes

ctrl.publish_cmd(0, 0, ControlCmd.STARTTEACH, 0) # Begin teaching
sleep(10) # Record the taught motion
ctrl.publish_cmd(0, 0, ControlCmd.SAVETEACH, 1) # End and save the teaching action, specifying index 1.
sleep(2) # Allow the motion control program to complete the save process to prevent it from being interrupted by the next command.
ctrl.publish_cmd(0, 0, ControlCmd.PLAYTEACH, 1) # play taught-motion file 1
tip

Only when action is one of the following modes: PLAYTEACH / WALK / SWING /CHEER / SHAKE / DEFAULT

x and yaw and y will take effect to control the robot's movement; in other modes, x and yaw and yare invalid.

Subscribe to robot hardware status information

Function Namesubscribe_robot_hardware_status
Function Prototypevoid subscribe_robot_hardware_status(RobotHardwareStatusCallback callback);
Function OverviewSubscribe to robot hardware status information
Parameter- callback: callback function for processing robot status data
Return ValueNone
Remarks

C++ Example:

ctrl->subscribe_robot_hardware_status(
[](const RobotHardwareStatus &status) {
latest_hw_status = status;
});

Python Example:

def _on_hw_status(status):
global latest_hw_status
atest_hw_status = status

ctrl.subscribe_robot_hardware_status(_on_hw_status)
Parameter NameDefine PrototypeParameterDescription
RobotHardwareStatus
struct RobotHardwareStatus {
NingImuData imu_data;
joydata remote_data;
std::array<MotorState, 18> motor_data;
int workmode;
};
imu_dataIMU data
remote_dataController Data
motor_dataMotor Data
workmodeCurrent operating mode

workmode value reference table

The workmode value is only valid in highcontroller mode

Workmode值Description
0Enabled Mode
1Ready Mode
2Walking Mode
3Running Mode
4Factory preset action: wave
5Factory preset action: handshake
6actory preset action: cheer
7Start teaching
8End Teaching
9Taught-motion playback
10Taught-motion saving
11Protection Mode
12Yingge dance (long version)
13Yingge dance (short version)
14Cha-Cha
15Broadcast exercise
16Spring Festival dance
17Cartwheel
18Controlled fall
19Disabled Mode
caution

Saving a Taught Motion

After the SDK sends a SAVETEACH command to the robot, the robot will sequentially return three statuses: Exit Teaching Save Teach 1 Save Teach 2

caution

Protection Mode

Under the standing control strategy (walking, teaching, dancing, etc.), the motion control program continuously monitors the IMU attitude data.

When the system detects that the attitude deviates from the standing stability range and exceeds the preset threshold, it will immediately trigger the protection mechanism and forcibly switch to the safe mode.

In Protection Mode:

  • All joints of the body enter a disabled state (the motor stops active output)

  • The current motion control policy is terminated

  • Execution of further motion commands is blocked

The purpose of this mechanism is as follows:

  • To prevent the robot from continuously outputting control torque during a fall or instability

  • To avoid secondary injury caused by uncontrolled swinging of the limbs

  • To mitigate potential damage to the equipment itself and the surrounding environment

This protection logic, as a underlying safety protection mechanism, enjoys the highest priority and will not be affected by upper-layer control commands.

Controller Data Structure

Parameter NameDefine PrototypeExample ValueDescription
joydata
struct joydata {
double axes[3];
int button[14];
};
axesRemote sensing linear joystick values of the controller
buttonButton press mapping values of the controller (1: pressed, 0: released)
Joystick MappingMapping DescriptionScope
axes[0]Robot turn value (> 0: left turn)[-1, 1]
axes[2]Robot translation value (> 0: leftward)[-1, 1]
axes[1]Robot longitudinal movement value (> 0: forward)[-1, 1]

IMU State Data Structure

Parameter NameDefine PrototypeExample ValueDescription
NingImuData
struct NingImuData {
double ori[4];
double ori_cov[9];
double angular_vel[3];
double angular_vel_cov[9];
double linear_acc[3];
double linear_acc_cov[9];
};
oriAttitude Quaternion
ori_covAttitude covariance
angular_velAngular velocity
angular_vel_covAngular velocity covariance
linear_acclinear acceleration
linear_acc_covLinear acceleration covariance

Motor status data structure

Parameter NameDefine PrototypeExample ValueDescription
MotorState
struct MotorState {
double pos;
double vel;
double tau;
uint16_t motor_id;
uint8_t error;
int temperature;
};
posMotor position
velMotor velocity
tauMotor torque
motor_idMotor ID
error
Motor Error Codes:
  • 02H: Motor overcurrent
  • 03H: Motor undervoltage
  • 04H: Motor encoder error
  • 06H: Motor brake overvoltage
  • 07H: DRV driver error
  • 08H: Overvoltage
  • 09H: Undervoltage
  • 0AH: Overcurrent
  • 0BH: MOS over-temperature
  • 0CH: Motor coil over-temperature
  • 0DH: Communication loss
  • 0EH: Overload
temperatureTemperature

4.Motion Control State Transition Flowchart​

danger

Note: During the development process with HighController, please follow the above flow chart for mode switching to ensure rationality and safety.

5.Development Examples​

In the SDK folder, example_high. cpp and test_high.py provide a sample demo, which is used to parse the input data of the Aolion Controller, and generate corresponding control commands according to the controller operations to send to the robot.

(VI) Motion Control Development — Lowcontrol​


tip

About Motion Control Development

Lowcontrol opens the motor control interface in the motion control program to the SDK, allowing users to directly adjust the underlying motor parameters at a control frequency of 500Hz. Combined with the deployment of reinforcement learning algorithms, it enables deep customization of the N2's motion capabilities, allowing it to complete complex behaviors such as diverse new movements and dances.

caution

Note: Only the EDU version of N2 supports LowController development

1.N2 Training Framework​

https://github.com/Noetix-Robotics/noetix_n2_gym

2.Lowcontrol Architecture Diagram​

image.png

(1) Status data reporting

After the Client SDK establishes a connection with the robot motion control program, the motion control program will continuously push real-time robot status information to the Client, including:

  • Whole-body motor parameter data (pos: position, vel: velocity, tau: torque, kp, kd, temperature, error)

  • IMU status data

  • Aolion controller data (used to synchronize manual input or assist control)


(2) Client-side control computation

The Client, in combination with its own algorithm (usually a reinforcement learning model), performs real-time policy computation to generate the target expected values (such as target position, etc.) for each motor, writes the motor control command array into the buffer, and then delivers it to the motion control program.


(3) Mechanism of motion control program

After receiving the motor command array dispatched by the client, the motion control program performs no high-level policy computation; Instead, it directly forwards the control parameters to the hardware control layer.


(4) Hardware execution layer

The hardware layer receives the target parameters of the motor, executes the control commands, and drives the motor to complete the expected actions.


In LowControl mode:

  • The reinforcement learning model is deployed on the client side

  • Users can directly participate in motor-level control.

  • The motion control program is mainly responsible for communication and secure forwarding.

  • The control frequency can reach up to 500Hz

This mode features higher control freedom and flexibility, but it also means:

  • Higher requirements for algorithm stability.

  • Stricter requirements for real-time performance and system security

  • A potential direct impact on robot motion safety if the control strategy is unstable.

3.Lowcontrol Operation Flowchart​

image.png

(1) Initialization phase (init)

After the system starts, complete the following initialization steps:

  1. Establish a communication connection between the client and the robot motion control program

  2. Register the callback function for receiving robot status data

  3. Create send_thread data transmission thread


(2) Status data callback mechanism

The motion control program continuously pushes robot status data to the client.

After receiving the data, the callback function encapsulates it and stores it in the corresponding buffer or global variable:

  • motor_state_buffer_: Motor Status Buffer

  • imu_buffer_: IMU status buffer

  • joy_buffer_: controller data buffer

This stage is only responsible for data reception and caching, and does not participate in control policy computations.


(3) send_thread (data sending thread)

The data transmission thread also runs at a 2 ms cycle:

  • If motor_cmd_buffer_ is not empty

  • Read the latest motor control commands

  • Send the motor target array to the motion control program

The motion control program only forwards the data to the hardware layer and does not participate in high-level control decisions.


(4) Architectural Features

The core features of the Lowcontrol mode are as follows:

  • Client directly participates in motor-level control

  • Reinforcement learning or custom control algorithms run on the client

  • The motion control program is no longer responsible for high-level policy computation, and only undertakes the responsibilities of communication and secure forwarding

  • The control frequency can reach up to 500Hz

This mode offers higher control flexibility and algorithmic plasticity, but at the same time, it imposes higher requirements on:

  • Real-time performance

  • Algorithm stability

  • Thread safety and scheduling accuracy

4.Joint Motor Information​

IDNameJointTorqueAngle RangeRadian Range
0arm_l1_jointLeft arm — shoulder pitch27N.m-155155-2.7052.705
1arm_l2_jointLeft arm — shoulder roll27N.m012002.094
2arm_l3_jointLeft arm — upper-arm yaw27N.m-155155-2.7052.705
3arm_l4_jointLeft arm — elbow pitch27N.m-10357-1.7980.995
4leg_l1_jointLeft leg — hip yaw90N.m-3757-0.6460.995
5leg_l2_jointLeft leg — hip roll90N.m-3757-0.6460.995
6leg_l3_jointLeft leg — thigh pitch150N.m-9045-1.5710.785
7leg_l4_jointLeft leg — knee pitch (linkage)150N.m012602.199
8leg_l5_jointLeft leg — shank/ankle pitch (linkage)70N.m-5743-0.9950.750
9arm_r1_jointRight arm — shoulder pitch27N.m-155155-2.7052.705
10arm_r2_jointRight arm — shoulder roll27N.m012002.094
11arm_r3_jointRight arm — upper-arm yaw27N.m-155155-2.7052.705
12arm_r4_jointRight arm — elbow pitch27N.m-10357-1.7980.995
13leg_r1_jointRight leg — hip yaw90N.m-3757-0.6460.995
14leg_r2_jointRight leg — hip roll90N.m-3757-0.6460.995
15leg_r3_jointRight leg — thigh pitch150N.m-9045-1.5710.785
16leg_r4_jointRight leg — knee pitch (linkage)150N.m012602.199
17leg_r5_jointRight leg — shank/ankle pitch (linkage)70N.m-5743-0.9950.750

MotorCmd. pos values are specified in radians.

5.Aolion Controller Data Mapping​

Aolion Controller. The button[] and key mapping table are as follows:

Button DescriptionButton index
Right Shoulder Button1
Left Shoulder Button2
X5
Y6
B7
A8
+9
-10
None11
Press the left joystick12

Joystick Data Range

Minimum ValueMaximum Value
-11

6.Common Interfaces and Usage Routines of LowController​

LowController Interface
Interface NameInterface Descriptionreturn type
instanceObtain the singleton pointer of LowControllerobject pointer
initInitialize the LowController objectNone
set_jointWrite the motor control command into the bufferNone
subscribe_robot_hardware_statusSubscribe to robot hardware status informationNone

Obtaining the LowController Singleton

Function Nameinstance
Function Prototypestatic LowController *Instance()
Function OverviewObtain the LowController singleton
ParameterNone
Return ValuePointer to the LowController singleton object
Remarks

C++ Example:

LowController *ctrl = LowController::Instance();

Python Example:

ctrl = LowController.instance()

Initializing the LowController Object

Function Nameinit
Function Prototypebool init()
Function OverviewLowController Object Initialization
ParameterNone
Return Valuebool
Remarks

C++ Example:

ctrl->init();

Python Example:

ctrl.init()

Writing the Motor Control Command Array into the Buffer

Once the commands have been written into the buffer, they are sent automatically by the send_thread thread

Function Nameset_joint
Function Prototypevoid set_joint(std::array<MotorCmd, 18> motorcmd)
Function OverviewSet joint data
Parameter- motorcmd: motor command structure
Return ValueNone
Remarks
Parameter NameDefine PrototypeExample ValueDescription
MotorCmd
struct MotorCmd {
double pos;
double vel;
double tau;
double kp;
double kd;
uint16_t motor_id;
};
posMotor position
velMotor velocity
tauMotor torque
kpPID parameter
kdPID parameter
motor_idMotor ID
danger

When dispatching motor control commands, strictly follow the parameter ranges specified in .

C++ Example:

std::array<MotorCmd, 18> motorcmd;
// Algorithm logic omitted...
ctrl->set_joint(motorcmd);

Python Example:

cmds = [MotorCmd() for _ in range(18)]
# Algorithm logic omitted...
ctrl.set_joint(cmds)

Subscribe to robot hardware status information

function namesubscribe_robot_hardware_status
function prototypevoid subscribe_robot_hardware_status(RobotHardwareStatusCallback callback);
Function OverviewSubscribe to robot hardware status information
Parameter- callback: callback function for processing robot status data
return valueNone
RemarksThe usage is the same as that of HighController subscribe_robot_hardware_status

7.Development Example​

examples/cpp/ example_policy_walk runs a sim2real deployment (on-robot deployment of a trained model) of an 18-DOF in-place stepping policy for the N2 (policy/policy\_user\.onnx), and provides a set of reinforcement learning deployment interfaces based on that policy

Function NameloadModel
Function Prototypebool loadModel(std::string modelpath)
Function OverviewLoad self-owned models
Parameter- modelpath: Model path (the current absolute path where the program is located)
Return Valuetrue: loading succeeded; false: loading failed
Remarks
Function Nameonnxdatainit
Function Prototypevoid onnxdatainit()
Function OverviewInitialize ONNX data
ParameterNone
Return ValueNone
Remarks
Function Namegetmodelparam
Function Prototypebool getmodelparam()
Function OverviewObtain model parameters from the yaml file
ParameterNone
Return Valuetrue: the YAML file is read successfully; false: the YAML file fails to be read
Remarks
Function Namesetparameter
Function Prototypevoid setparameter(Command &cmd,bool* isfirst)
Function OverviewSet the x / y / z whole-body machine control parameters
Parameter- cmd: set command
- isfirst: Indicates whether it is the first setup
return valueNone
Remarks
Function Nameupdatestateestimation
function prototypebool updatestateestimation()
Function OverviewUpdate the status, including joint angles, IMU data, etc. , and obtain model parameters from the yaml file
ParameterNone
Return Valuetrue: the YAML file is read successfully; false: the YAML file fails to be read
Remarks
Function NamecomputeObservation
Function Prototypevoid computeObservation()
Function OverviewCalculate the observation coefficients
ParameterNone
Return ValueNone
Remarks
Function NamecomputeActions
Function Prototypevoid computeActions()
Function OverviewCalculate the final action
ParameterNone
Return ValueNone
Remarks

Controller Operation Procedure

Usage Steps
+All joints return to the zero position and enter damping mode
LB & -The limbs bend slightly; the robot enters the pre-policy Ready Mode
LB & XEnter policy-controlled in-place stepping mode

(VII) Rapid Development​

All the following operations are performed on the N2 computing board. The computing board already has the required compilation environment installed; alternatively, you can deploy the compilation environment using Docker.

For the external-development deployment environment, see: SDK 编译环境部署流程

tip

About External Development

Since the motion control board of humanoid products is not open to the public, user programs cannot be directly deployed and run on the motion control board, so an additional computing carrier is required to execute user programs.

If your robot model is not equipped with a compute board, you must adopt the “external development” approach: use your own compute board or host computer and connect it to the port on the N2's back via a network cable to communicate with the motion control board.

Since the motion control board only allows communication with the fixed IP of the original computing board, and the communication is based on the wired connection of the internal switch, the external device needs to be configured with the same IP as the original computing board to simulate the original computing board and complete the access.

Logging in to the computing board via SSH (wired connection)

ssh noetix@192.168.55.101

Logging in to the compute board via SSH (wireless connection; the wireless IP can be found by running ifconfig after logging into the compute board via SSH)

ssh noetix@[robot WIFI-IP]

1.SDK Directory Structure​

.
├── build.sh # Compilation script
├── CMakeLists.txt
├── config # Configuration file
├── dds # DDS library files
├── examples # Example code
├── include
├── lib # Dynamic library files
├── LICENSE
├── policy # Model file
├── pybind # pybind file
└── README.md

2.Docker Development Environment Mirror Deployment​

noetix_dds.tar.gz

caution

Note: This mirror package is for the aarch64 architecture and can only be deployed on computers with the aarch64 architecture.

  1. Extract the archive
tar -zxvf noetix_dds.tar.gz

After extraction, the archive contains noetix_dds. tar development image file noetix_dds. yaml configuration deployment file

version: "3.8"

services:
noetix_dds:
image: noetix_dds:arm64
container_name: noetix_dds
network_mode: host
volumes:
- /home/noetix/work:/home/noetix/work:rw # Mount working directory
# /home/noetix/work The part before the colon should be changed to the user's working directory; create a directory named /home/noetix/work/.
stdin_open: true
tty: true

  1. Deployment
docker load -i noetix_dds.tar
docker images # Confirm that the noetix_dds arm64 image exists.
mkdir -p /home/noetix/work # Create a working directory; the user can choose it
docker compose -f noetix_dds.yaml up -d # deploy
docker ps # Check if noetix_dds exists.

  1. Enter the dock container
docker exec -it noetix_dds /bin/bash

You can start development by simply placing the DDS SDK in the working directory afterwards.

3.Compile SDK​

cd noetix_sdk_n2
./build.sh # One-click compilation script

After successful compilation, executable files will be generated in the root directory of the SDK example_low and example_high , and the pybind libraries highcontrol_py and lowcontrol_py for Python calling will be generated in the build directory

4.Running the Programs​

C++

cd noetix_sdk_n2
sudo ./build/example_high # or sudo ./build/example_low

Python

cd noetix_sdk_n2
python3 examples_py/test_low.py # python3 examples/py/test_high.py
caution

Safety Tips

During the debugging process, please use the robot hanger throughout the whole process to avoid losses caused by out-of-control wrong programs.

(VIII) Common Issues and Precautions​

  1. DDS Client Demo: Runtime Error (1)

ARM architecture:

error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory

libssl1.1_1.1.1f-1ubuntu2.16_arm64.deb

sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.16_arm64.deb

X86 Architecture:

./highcontrol: error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory

libssl1.1_1.1.1f-1ubuntu2_amd64.deb

sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
©Beijing Noetix Robotics Technology Group Co., Ltd.
Jing ICP Bei No. 2024092119-1 | Jing Gong Wang An Bei No. 11010802045221
Internet Filing No. 110114067446901260013
Beijing-SongYanDongLiFangShengJiQiRen-20260901S0213
Beijing-SongYanDongLiRenXingJiQiRen-20260901S0214