BRUCE Wiki - User contributions [en]

Main Page

2025-01-20T08:55:15Z

Jshen: /* Operating */

Welcome to BRUCE (Bipedal Robot Unit with Compliannce Enhanced) Wiki, where we update infomation on hardware and software of BRUCE.

= About BRUCE Project =

BRUCE is an open-platform project led by [https://www.westwoodrobotics.io/ Westwood Robotics].
It focuses on the development of a low-cost kid-size humanoid robot for research and education.

=== Licensing ===

BRUCE is dual-licensed under both commercial and open-source licenses.
The commercial BRUCE license gives you the full rights to create and distribute the platform on your own terms without any open-source license obligations.
BRUCE is also available under version 3 (or later version) of the GNU General Public License (GPL), which is ideal for use cases such as open-source projects with open-source distribution, student/academic purposes, hobby projects, internal research projects without external distribution, or other projects where all GPL obligations can be met.
Read the full text of [https://www.gnu.org/licenses/gpl-3.0.html the GNU GPL version 3] for details.

= Introduction =
=== Hardware Platform ===

[[File:BRUCE_cover_photo.jpg|thumb|Photo of BRUCE platform]]

[[File:BRUCE_hardware_overview.png|thumb|BRUCE hardware overview]]

[[File:BRUCE_schematic_diagram.jpg|thumb|BRUCE schematic diagram]]

[[File:BRUCE_software_architecture.png|thumb|BRUCE software architecture]]

BRUCE has a total height of 70 cm adapting an average human body proportion. It is composed of a torso, two 3-DoF arms, and two 5-DoF legs.
Each arm of BRUCE has a ball shoulder joint and a single DoF elbow joint.
Each leg of BRUCE has a spherical hip joint, a single DoF knee joint, and a single DoF ankle joint.
Each foot has a line contact with the ground.
To have better torque transparency and compliance to the unknown environment, proprioceptive actuation is equipped for each leg joint, using the [https://www.westwoodrobotics.io/koala-bear/ Koala BEAR] actuators.
Moreover, BRUCE's legs are designed to have low inertia for performing highly dynamic motions. A 2-DoF parallel actuation configuration realized by a cable-driven differential pulley system is applied to the hip joint to reduce the mass and inertia of the femur link. Meanwhile, two pairs of 4-bar linkage mechanisms are used to relocate the ankle actuator to the femur link for the light weight of the tibia link.
Finally, to ensure reliable ground contact information, a sensing foot is designed based on the working principle of an electronic switch.

BRUCE is fully untethered.
All the electronics are directly mounted onto the torso for easy installation and better weight distribution.
[https://www.khadas.com/edge2 Khadas Edge2] with RK3588S is utilized as the onboard computing resource.
A 14.8V 3000mAh Li-ion battery is used to power the whole system with a running time of approximately 20 minutes.
For the sake of safety during operation, a wireless E-Stop built in-house is mounted onboard as well to put BEAR actuators into damping mode in emergencies.
In total, BRUCE has a net weight of around 4.8 kg.
A hardware overview and schematic diagram of BRUCE are shown in the images.

=== Software Architecture ===

To make BRUCE favorable to dynamic behaviors which require fast response, the overall software framework is developed in a multithreaded environment, which includes a state estimation thread combined with robot model computation, a low-level whole-body control thread, a high-level footstep planning thread, and a top-level user input thread.
The main advantage of multithreading is that the idle time of the CPU can be kept to minimum since the waiting time for sensor response can be well distributed and utilized, which leads to faster overall execution as the CPU would have been idle if only a single thread was executed.
Data communication utilizes a custom shared memory library. All programs are implemented in Python while some parts, including kinematics, dynamics, and state estimation, are precompiled using [https://numba.pydata.org/ Numba] for acceleration.

= Working with BRUCE =

BRUCE is ready to go with the [https://github.com/Westwood-Robotics/BRUCE-OP default software] provided. Below are the detailed instructions on how to operate and maintain the platform.

=== Attention ===

* Always remember to press the '''E-STOP''' immediately in emergencies!
* Your system may need some fine tuning before it can perform perfectly, i.e., due to slight differences in joint resistance and part tolerances, systems may vary in tuning parameters.

=== Dependencies ===

* Python 3.6+ with pip, numpy, pyserial, termcolor, matplotlib, scipy, osqp, numba, dynamixel, posix_ipc
* [https://github.com/Westwood-Robotics/PyBEAR-WR PyBEAR] for communication with the BEAR actuators

=== Serial Port & MAC Address ===

Please config the serial port names (of BEAR, DYNAMIXEL, and BRUCE SENSE) and MAC address of your gamepad (if applicable) in <code>BRUCE/BRUCE_SERIAL_PORT</code> or <code>BRUCE/BRUCE-OP/Settings/BRUCE_macros.py</code> (line 272-283) for your BRUCE before use.

=== Allow Executing Bash/Binary File as Program ===

# Download the binary demo controller according to [https://github.com/Westwood-Robotics/BRUCE-OP/blob/main/Play/Demo/README.md README].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the following commands.
<code>
chmod +x Play/bootup.sh

chmod +x Play/bootup_gamepad.sh

chmod +x Play/sim_bootup.sh

chmod +x Play/terminate.sh

chmod +x Play/Demo/low_level-aarch64

chmod +x Play/Demo/low_level-x86_64

chmod +x Play/Demo/high_level-aarch64

chmod +x Play/Demo/high_level-x86_64

chmod +x Startups/startup_setup.sh

chmod +x Startups/usb_latency_setup.sh
</code>

=== Startup Setup Before Launch ===

BRUCE after VERSION 0.0.4 will be automatically configured at bootup with [https://help.ubuntu.com/stable/ubuntu-help/startup-applications.html.en Startup Applications].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the bash file <code>Startups/startup_setup.sh</code>.

=== Operating ===

''Quick Launch''

# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Config launch setup in <code>Play/config.py</code>.
# Run the bash file and follow the guidance <code>Play/bootup.sh</code>.
# Terminate in the end <code>Play/terminate.sh</code>.

''Full Operating''

# Make all terminals go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# In terminal 1, run USB low latency setup <code>Startups/usb_low_latency.sh</code>.
# In terminal 1, run shared memory modules <code>python3 -m Startups.memory_manager</code>.
# In terminal 1, start the DYNAMIXEL motor thread <code>python3 -m Startups.run_dxl</code>.
# In terminal 2, start the BEAR actuator thread <code>python3 -m Startups.run_bear</code>.
# In terminal 3, initialize BRUCE <code>python3 -m Play.initialize</code> and choose <code>s</code>. If the joint angles are weird, a [[Main_Page#Calibration|calibration]] needs to be conducted.
# In terminal 3, start the sense communication thread after BRUCE can stand on the ground on its own <code>python3 -m Startups.run_sense</code>.
# In terminal 4, start the state estimation thread <code>python3 -m Startups.run_estimation</code>.
# In terminal 5, start the low-level control thread <code>python3 -m Play.Walking.low_level</code>.
# In terminal 6, start the high-level planning thread <code>python3 -m Play.Walking.high_level</code>.
# In terminal 7, start the top-level user keyboard input thread <code>python3 -m Play.Walking.top_level</code>.
# You can now play with BRUCE and remember to press the '''E-STOP''' in emergencies. You can recover BRUCE by releasing the '''E-STOP''' and then repeating Steps 4-11.

=== BEAR Calibration ===

[[File:BRUCE_nominal_position.jpg|thumb|BRUCE nominal position]]
[[File:BRUCE_calibration_position.jpg|thumb|BRUCE calibration position]]

The nominal posture for BRUCE is all limbs completely sprawled out as shown in the image. Note that the hip, knee, and ankle joints are aligned. You can check it with the following instructions:
# Go through Steps 1-5 in ''Full Operating''.
# In terminal 3, entering the following command <code>python3 -m Play.initialize</code> and enter <code>n</code>.

If the leg configuration is off, the related BEAR actuators need to be re-calibrated to the correct zero position with the following instructions:
# Disable the BEAR actuators by pressing the '''E-STOP'''.
# Adjust BRUCE to the calibration posture as shown in the image. Use the calibration tool if necessary.
# In terminal 3, run the calibration script <code>python3 -m Util.BEAR_calibration</code>.
# Select the actuator number that you wish to home and follow the guidance.

=== Bluetooth Gamepad ===
Beginning Jan 20, 2024, all BRUCE ships with a Bluetooth Gamepad that has a screen, with wireless '''E-STOP''' integrated. Wireless '''E-STOP''' remote will not be included in the box.

'''ATTENTION:''' Do '''NOT''' use the Wireless '''E-STOP''' remote together with this gamepad. Signals will have interference and '''E-STOP''' will malfunction.
[[File:BRUCE Gamepad.jpg|none|thumb|BRUCE BLE Gamepad]]There are two joysticks with push-buttons, two shoulder rollers with push-buttons, and 14 buttons on the remote. All buttons are labeled in the following figure:
[[File:BLE Remote.jpg|none|thumb|869x869px]]
After BRUCE is launched, the screen is used to show the control commends and robot status:
[[File:Gamepad Legend.png|none|thumb|892x892px]]
Currently implemented Key Combinations/Commands on BRUCE-OP are:
{| class="wikitable"
|+'''BRUCE Gamepad Operation'''
!Gamepad Operation
!Function
|-
! colspan="2" | ''To Change Mode''
|-
|Start + Back
|Standing
|-
|Start + X
|Running
|-
|Start + Y
|Walking
|-
! colspan="2" | ''In Standing Mode''
|-
|Up/Down
|CoM X Position
|-
|Left Axis X
|CoM Y Position
|-
|Left Axis Y
|CoM Z Position
|-
|Right Axis X
|Body Roll Angle
|-
|Right Axis Y
|Body Pitch Angle
|-
|Right Shoulder Roller
|Body Yaw Angle
|-
! colspan="2" | ''In Walking/Running Mode''
|-
|Left Axis X
|CoM X Velocity
|-
|Left Axis Y
|CoM Y Velocity
|-
|Right Shoulder Roller
|Body Yaw Rate
|-
|Start + Right Shoulder Roller
|Right Foot Yaw Angle
|-
|Start + Left Shoulder Roller
|Left Foot Yaw Angle
|-
|Start + Right/Left
|Foot Clearance
|-
! colspan="2" | ''Others''
|-
|A
|Hand Wave
|-
|Back
|Restore
|-
|Fn
|Cooling Speed (-)
|-
|Start + Fn
|Cooling Speed (+)
|-
|Left Axis Z + Right Axis Z
|Terminate (Software '''E-STOP''')
|}

= For Developers =

=== Simulation Environment ===
BRUCE Gym simulation environment is based on a custom library to interact with Gazebo. Please refer to <code>BRUCE-OP/Simulation/README.md</code> for more information.

=== Power Hub ===
The Power Hub on BRUCE is located right above its battery, and it serves as the hub that collects and distributes signal and power for BRUCE. See the figure below for pinout definition:[[File:Power_Hub_RevB.jpg|thumb|Power Hub|none|400x400px]]

=== Khadas Edge2 ===

If you want to make further development with the onboard [https://www.khadas.com/edge2 Khadas Edge2], please refer to its online documents [https://docs.khadas.com/products/sbc/edge2/start here]. To use external keyboard and mouse, you can unplug the original 4-wire USB-C signal cable (the other one is 2-wire for power delivery) without disassembly.
[[File:Edge2.jpg|none|thumb|821x821px]]

=== BRUCE SENSE ===
BRUCE SENSE refers to the Raspberry Pi Pico on BRUCE, which is used to collect the IMU and foot contact data, as well as to control the cooling system for BEARs. Refer to the figure below for pinout definition on BRUCE SENSE:[[File:BRUCE_SENSE.jpg|thumb|BRUCE SENSE|none|450x450px]]An example of how to use it is provided (<code>BRUCE-OP/Examples/bruce_sense</code>). Users can use Arduino IDE to upload its code (<code>BRUCE-OP/Library/BRUCE_SENSE/pico/pico.ino</code>). The LED on BRUCE SENSE indicates the following status.
{| class="wikitable"
|+BRUCE SENSE LED
!Color
!Status
|-
|Green
|Initialization
|-
|White
|Idle Mode
|-
|Off
|Nominal Mode
|-
|Cyan
|Calibration Mode
|-
|Red
|Right Foot in Contact
|-
|Blue
|Left Foot in Contact
|-
|Amber
|Cooling System On
|-
|Yellow
|Delay Warning
|}

=== State Estimation ===

Two versions of state estimation are provided. One is using complementary filter solely, the details of which are described in the 4th paper of [[Main_Page#Reference|Reference]]. The other is using complementary filter for the base orientation (similar to the former) while Kalman filter for the base position and velocity, which greatly enhances the estimation performance. Interested users can refer to the document [https://wiki.bruce-op.com/uploads/BRUCE_state_estimation.pdf here].

=== IMU Calibration ===
It is recommended to calibrate the IMU bias on your BRUCE for better performance of the state estimation, in case a new IMU is used.
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the calibration script <code>python3 -m Util.imu_calibration</code>. Make sure the IMU is placed as flat as possible and do not move the IMU in calibration.

=== Wireless ESTOP Lite ===
The Wireless ESTOP Lite system has been applied on BRUCE and other systems that are powered with BEAR actuators and has been a very handy gadget. You can find more details [https://github.com/Westwood-Robotics/Wireless_ESTOP here].

=== Performance Tuning [Latest Version] ===
While BRUCE is in a healthy functional status, tuning some parameters can potentially improve its performance, stability, or further tailor it to your specific demands, e.g.,

* Demo (in <code>BRUCE-OP/Play/Demo/demo_macros.py</code>)

# <code>bx_offset</code> & <code>by_offset</code>: CoM velocity adjustment in moving [m]
# <code>COM_VELOCITY_LIMIT</code>: CoM velocity limit in moving [m]
# <code>px_offset</code>: CoM position adjustment in standing [m]

* OP (in <code>BRUCE-OP/Play/Walking/walking_macros.py</code>)

# <code>bx_offset</code> & <code>by_offset</code>: CoM velocity offset compensation [m]
# <code>ka</code>: x position of CoM in standing

=== Other Accessories ===

==== 1. Khadas USB Extension ====
There are two extra USB ports on the Khadas but they are covered by BRUCE's body rack so not very easy to access. For those who needs better access to these extra USB ports, we have developed an extension that shift the connection to the top of the body and exposes them better. Although one of them is USB3.0, only USB2.0 is supported by this extension for now.
{|
![[File:USB-EXT.png|none|thumb|300x300px]]
![[File:USB-EXT On BRUCE.png|none|thumb|312x312px]]
|}
Gerber files and 3D models of related parts can be downloaded in the Download section, or you can buy parts from us directly.

= Troubleshooting =

====== Using Linux Screen ======
There are multiple threads running concurrently on BRUCE, and it is achieved with multiple windows under one screen session. It is recommended to go through [https://www.gnu.org/software/screen/manual/screen.html this manual] to learn the basic operation and functions of Linux Screen.

====== Looking Into Malfunction ======
When BRUCE failed to perform a certain motion or fell, you should be able to see errors and more specific details on the failure in each thread. Follow the steps below to visit each thread for error reports:

# If operating the robot via Bluetooth remote, login via SSH to start; if already operating via SSH, jump to step 3.
# Attach to the BRUCE screen session. Use command <code>screen -ls</code> to show all opened screen sessions, find the session with BRUCE, and take note of the ID number of the session, then use <code>screen -r ID-of-BRUCE-SESSION</code> to reattach to the BRUCE session.
# Use command <code>Ctrl+A+#</code> to jump into each window of the screen session to find out the error printout of each thread. # is the number of a screen window, the range is 0~6.

For example, you might see low-level error in the TOP-LEVEL screen window, and once jumped into the LOW-LEVEL window, you might find out that the error is triggered by run-bear thread.

= Future Work =

# Add more explanation to the code, such as line by line legKF and est_KF reference. (Q1 2024)
# <s>New Body that exposes the two USB Type A ports on Khadas. (Q1 2024)</s>
#* The better solution is to design a simple adaptor PCB instead of redesigning the frame. Different groups would have very different applications thus the peripherals intended to be connected can be very different, as well as the desired mounting location, which then leads to very specific requirements of wire management. By making an adaptor board the current compact design of BRUCE can be kept while specific requirement for wire management can all be met.
# Provide a dual camera module.(Q1 2024)
# Option of a new pair of leg using KBMB as Knee Actuator for better payload capacity with the tradeoff of dynamic motions.(Q2 2024)

= Downloads =

# [https://wiki.bruce-op.com/uploads/BRUCE_V1.4_DUMMY.STEP BRUCE V1.4 3D Model]
# [[3D Printed Parts]]
# [[Simulation Files]]
# [[2D Drawings|2D drawing of Signal Cables]]
# [https://wiki.bruce-op.com/uploads/HIP_CALIBRATION_RevC.STEP Calibration Tools]
# [https://wiki.bruce-op.com/uploads/demo_controller_0.0.6.zip Binary Demo Controller]
# [[Other Accessories]]

= Reference =
Publications on BRUCE development:

# X. Zhang, "[https://escholarship.org/uc/item/9dk9r8d3 Application of Proprioception Quasi-Direct Drive Actuators on Dynamic Robotic Systems]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2019.
# Y. Liu, J. Shen, J. Zhang, X. Zhang, T. Zhu and D. Hong, "[https://ieeexplore.ieee.org/document/9811790 Design and Control of a Miniature Bipedal Robot with Proprioceptive Actuation for Dynamic Behaviors]," 2022 IEEE International Conference on Robotics and Automation (ICRA), 2022, pp. 8547-8553.
# J. Shen, J. Zhang, Y. Liu, and D. Hong, "[https://ieeexplore.ieee.org/document/10000075 Implementation of a Robust Dynamic Walking Controller on a Miniature Bipedal Robot with Proprioceptive Actuation]," 2022 IEEE-RAS International Conference on Humanoid Robots (Humanoids), 2022, pp. 39-46.
# J. Shen, "[https://escholarship.org/uc/item/52q9d7vk Locomotion Analysis and Control of a Miniature Bipedal Robot]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2022.
# J. Zhang, "[https://escholarship.org/uc/item/8002g72b Towards Application on Optimization-Based Methods for Motion Planning of Legged Robots]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2023.
# J. Zhang, J. Shen, Y. Liu and D. Hong, "[https://arxiv.org/abs/2304.00536 Design of a Jumping Control Framework with Heuristic Landing for Bipedal Robots]," 2023 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2023, pp. 8502-8509.

= Contributing to BRUCE Wiki =
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Main Page

2024-09-04T04:33:34Z

Jshen: /* Downloads */

Welcome to BRUCE (Bipedal Robot Unit with Compliannce Enhanced) Wiki, where we update infomation on hardware and software of BRUCE.

= About BRUCE Project =

BRUCE is an open-platform project led by [https://www.westwoodrobotics.io/ Westwood Robotics].
It focuses on the development of a low-cost kid-size humanoid robot for research and education.

=== Licensing ===

BRUCE is dual-licensed under both commercial and open-source licenses.
The commercial BRUCE license gives you the full rights to create and distribute the platform on your own terms without any open-source license obligations.
BRUCE is also available under version 3 (or later version) of the GNU General Public License (GPL), which is ideal for use cases such as open-source projects with open-source distribution, student/academic purposes, hobby projects, internal research projects without external distribution, or other projects where all GPL obligations can be met.
Read the full text of [https://www.gnu.org/licenses/gpl-3.0.html the GNU GPL version 3] for details.

= Introduction =
=== Hardware Platform ===

[[File:BRUCE_cover_photo.jpg|thumb|Photo of BRUCE platform]]

[[File:BRUCE_hardware_overview.png|thumb|BRUCE hardware overview]]

[[File:BRUCE_schematic_diagram.jpg|thumb|BRUCE schematic diagram]]

[[File:BRUCE_software_architecture.png|thumb|BRUCE software architecture]]

BRUCE has a total height of 70 cm adapting an average human body proportion. It is composed of a torso, two 3-DoF arms, and two 5-DoF legs.
Each arm of BRUCE has a ball shoulder joint and a single DoF elbow joint.
Each leg of BRUCE has a spherical hip joint, a single DoF knee joint, and a single DoF ankle joint.
Each foot has a line contact with the ground.
To have better torque transparency and compliance to the unknown environment, proprioceptive actuation is equipped for each leg joint, using the [https://www.westwoodrobotics.io/koala-bear/ Koala BEAR] actuators.
Moreover, BRUCE's legs are designed to have low inertia for performing highly dynamic motions. A 2-DoF parallel actuation configuration realized by a cable-driven differential pulley system is applied to the hip joint to reduce the mass and inertia of the femur link. Meanwhile, two pairs of 4-bar linkage mechanisms are used to relocate the ankle actuator to the femur link for the light weight of the tibia link.
Finally, to ensure reliable ground contact information, a sensing foot is designed based on the working principle of an electronic switch.

BRUCE is fully untethered.
All the electronics are directly mounted onto the torso for easy installation and better weight distribution.
[https://www.khadas.com/edge2 Khadas Edge2] with RK3588S is utilized as the onboard computing resource.
A 14.8V 3000mAh Li-ion battery is used to power the whole system with a running time of approximately 20 minutes.
For the sake of safety during operation, a wireless E-Stop built in-house is mounted onboard as well to put BEAR actuators into damping mode in emergencies.
In total, BRUCE has a net weight of around 4.8 kg.
A hardware overview and schematic diagram of BRUCE are shown in the images.

=== Software Architecture ===

To make BRUCE favorable to dynamic behaviors which require fast response, the overall software framework is developed in a multithreaded environment, which includes a state estimation thread combined with robot model computation, a low-level whole-body control thread, a high-level footstep planning thread, and a top-level user input thread.
The main advantage of multithreading is that the idle time of the CPU can be kept to minimum since the waiting time for sensor response can be well distributed and utilized, which leads to faster overall execution as the CPU would have been idle if only a single thread was executed.
Data communication utilizes a custom shared memory library. All programs are implemented in Python while some parts, including kinematics, dynamics, and state estimation, are precompiled using [https://numba.pydata.org/ Numba] for acceleration.

= Working with BRUCE =

BRUCE is ready to go with the [https://github.com/Westwood-Robotics/BRUCE-OP default software] provided. Below are the detailed instructions on how to operate and maintain the platform.

=== Attention ===

* Always remember to press the '''E-STOP''' immediately in emergencies!
* Your system may need some fine tuning before it can perform perfectly, i.e., due to slight differences in joint resistance and part tolerances, systems may vary in tuning parameters.

=== Dependencies ===

* Python 3.6+ with pip, numpy, pyserial, termcolor, matplotlib, scipy, osqp, numba, dynamixel, posix_ipc
* [https://github.com/Westwood-Robotics/PyBEAR-WR PyBEAR] for communication with the BEAR actuators

=== Serial Port & MAC Address ===

Please config the serial port names (of BEAR, DYNAMIXEL, and BRUCE SENSE) and MAC address of your gamepad (if applicable) in <code>BRUCE/BRUCE_SERIAL_PORT</code> or <code>BRUCE/BRUCE-OP/Settings/BRUCE_macros.py</code> (line 272-283) for your BRUCE before use.

=== Allow Executing Bash/Binary File as Program ===

# Download the binary demo controller according to [https://github.com/Westwood-Robotics/BRUCE-OP/blob/main/Play/Demo/README.md README].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the following commands.
<code>
chmod +x Play/bootup.sh

chmod +x Play/bootup_gamepad.sh

chmod +x Play/sim_bootup.sh

chmod +x Play/terminate.sh

chmod +x Play/Demo/low_level-aarch64

chmod +x Play/Demo/low_level-x86_64

chmod +x Play/Demo/high_level-aarch64

chmod +x Play/Demo/high_level-x86_64

chmod +x Startups/startup_setup.sh

chmod +x Startups/usb_latency_setup.sh
</code>

=== Startup Setup Before Launch ===

BRUCE after VERSION 0.0.4 will be automatically configured at bootup with [https://help.ubuntu.com/stable/ubuntu-help/startup-applications.html.en Startup Applications].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the bash file <code>Startups/startup_setup.sh</code>.

=== Operating ===

''Quick Launch''

# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Config launch setup in <code>Play/config.py</code>.
# Run the bash file and follow the guidance <code>Play/bootup.sh</code>.
# Terminate in the end <code>Play/terminate.sh</code>.

''Full Operating''

# Make all terminals go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# In terminal 1, run USB low latency setup <code>Startups/usb_low_latency.sh</code>.
# In terminal 1, run shared memory modules <code>python3 -m Startups.memory_manager</code>.
# In terminal 1, start the DYNAMIXEL motor thread <code>python3 -m Startups.run_dxl</code>.
# In terminal 2, start the BEAR actuator thread <code>python3 -m Startups.run_bear</code>.
# In terminal 3, initialize BRUCE <code>python3 -m Play.initialize</code> and choose <code>s</code>. If the joint angles are weird, a [[Main_Page#Calibration|calibration]] needs to be conducted.
# In terminal 3, start the sense communication thread after BRUCE can stand on the ground on its own <code>python3 -m Startups.run_sense</code>.
# In terminal 4, start the state estimation thread <code>python3 -m Startups.run_estimation</code>.
# In terminal 5, start the low-level control thread <code>python3 -m Play.Demo.low_level</code>.
# In terminal 6, start the high-level planning thread <code>python3 -m Play.Demo.high_level</code>.
# In terminal 7, start the top-level user keyboard input thread <code>python3 -m Play.Demo.top_level</code>.
# You can now play with BRUCE and remember to press the '''E-STOP''' in emergencies. You can recover BRUCE by releasing the '''E-STOP''' and then repeating Steps 4-11.

=== BEAR Calibration ===

[[File:BRUCE_nominal_position.jpg|thumb|BRUCE nominal position]]
[[File:BRUCE_calibration_position.jpg|thumb|BRUCE calibration position]]

The nominal posture for BRUCE is all limbs completely sprawled out as shown in the image. Note that the hip, knee, and ankle joints are aligned. You can check it with the following instructions:
# Go through Steps 1-5 in ''Full Operating''.
# In terminal 3, entering the following command <code>python3 -m Play.initialize</code> and enter <code>n</code>.

If the leg configuration is off, the related BEAR actuators need to be re-calibrated to the correct zero position with the following instructions:
# Disable the BEAR actuators by pressing the '''E-STOP'''.
# Adjust BRUCE to the calibration posture as shown in the image. Use the calibration tool if necessary.
# In terminal 3, run the calibration script <code>python3 -m Util.BEAR_calibration</code>.
# Select the actuator number that you wish to home and follow the guidance.

=== Bluetooth Gamepad ===
Beginning Jan 20, 2024, all BRUCE ships with a Bluetooth Gamepad that has a screen, with wireless '''E-STOP''' integrated. Wireless '''E-STOP''' remote will not be included in the box.

'''ATTENTION:''' Do '''NOT''' use the Wireless '''E-STOP''' remote together with this gamepad. Signals will have interference and '''E-STOP''' will malfunction.
[[File:BRUCE Gamepad.jpg|none|thumb|BRUCE BLE Gamepad]]There are two joysticks with push-buttons, two shoulder rollers with push-buttons, and 14 buttons on the remote. All buttons are labeled in the following figure:
[[File:BLE Remote.jpg|none|thumb|869x869px]]
After BRUCE is launched, the screen is used to show the control commends and robot status:
[[File:Gamepad Legend.png|none|thumb|892x892px]]
Currently implemented Key Combinations/Commands on BRUCE-OP are:
{| class="wikitable"
|+'''BRUCE Gamepad Operation'''
!Gamepad Operation
!Function
|-
! colspan="2" | ''To Change Mode''
|-
|Start + Back
|Standing
|-
|Start + X
|Running
|-
|Start + Y
|Walking
|-
! colspan="2" | ''In Standing Mode''
|-
|Up/Down
|CoM X Position
|-
|Left Axis X
|CoM Y Position
|-
|Left Axis Y
|CoM Z Position
|-
|Right Axis X
|Body Roll Angle
|-
|Right Axis Y
|Body Pitch Angle
|-
|Right Shoulder Roller
|Body Yaw Angle
|-
! colspan="2" | ''In Walking/Running Mode''
|-
|Left Axis X
|CoM X Velocity
|-
|Left Axis Y
|CoM Y Velocity
|-
|Right Shoulder Roller
|Body Yaw Rate
|-
|Start + Right Shoulder Roller
|Right Foot Yaw Angle
|-
|Start + Left Shoulder Roller
|Left Foot Yaw Angle
|-
|Start + Right/Left
|Foot Clearance
|-
! colspan="2" | ''Others''
|-
|A
|Hand Wave
|-
|Back
|Restore
|-
|Fn
|Cooling Speed (-)
|-
|Start + Fn
|Cooling Speed (+)
|-
|Left Axis Z + Right Axis Z
|Terminate (Software '''E-STOP''')
|}

= For Developers =

=== Simulation Environment ===
BRUCE Gym simulation environment is based on a custom library to interact with Gazebo. Please refer to <code>BRUCE-OP/Simulation/README.md</code> for more information.

=== Power Hub ===
The Power Hub on BRUCE is located right above its battery, and it serves as the hub that collects and distributes signal and power for BRUCE. See the figure below for pinout definition:[[File:Power_Hub_RevB.jpg|thumb|Power Hub|none|400x400px]]

=== Khadas Edge2 ===

If you want to make further development with the onboard [https://www.khadas.com/edge2 Khadas Edge2], please refer to its online documents [https://docs.khadas.com/products/sbc/edge2/start here]. To use external keyboard and mouse, you can unplug the original 4-wire USB-C signal cable (the other one is 2-wire for power delivery) without disassembly.
[[File:Edge2.jpg|none|thumb|821x821px]]

=== BRUCE SENSE ===
BRUCE SENSE refers to the Raspberry Pi Pico on BRUCE, which is used to collect the IMU and foot contact data, as well as to control the cooling system for BEARs. Refer to the figure below for pinout definition on BRUCE SENSE:[[File:BRUCE_SENSE.jpg|thumb|BRUCE SENSE|none|450x450px]]An example of how to use it is provided (<code>BRUCE-OP/Examples/bruce_sense</code>). Users can use Arduino IDE to upload its code (<code>BRUCE-OP/Library/BRUCE_SENSE/pico/pico.ino</code>). The LED on BRUCE SENSE indicates the following status.
{| class="wikitable"
|+BRUCE SENSE LED
!Color
!Status
|-
|Green
|Initialization
|-
|White
|Idle Mode
|-
|Off
|Nominal Mode
|-
|Cyan
|Calibration Mode
|-
|Red
|Right Foot in Contact
|-
|Blue
|Left Foot in Contact
|-
|Amber
|Cooling System On
|-
|Yellow
|Delay Warning
|}

=== State Estimation ===

Two versions of state estimation are provided. One is using complementary filter solely, the details of which are described in the 4th paper of [[Main_Page#Reference|Reference]]. The other is using complementary filter for the base orientation (similar to the former) while Kalman filter for the base position and velocity, which greatly enhances the estimation performance. Interested users can refer to the document [https://wiki.bruce-op.com/uploads/BRUCE_state_estimation.pdf here].

=== IMU Calibration ===
It is recommended to calibrate the IMU bias on your BRUCE for better performance of the state estimation, in case a new IMU is used.
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the calibration script <code>python3 -m Util.imu_calibration</code>. Make sure the IMU is placed as flat as possible and do not move the IMU in calibration.

=== Wireless ESTOP Lite ===
The Wireless ESTOP Lite system has been applied on BRUCE and other systems that are powered with BEAR actuators and has been a very handy gadget. You can find more details [https://github.com/Westwood-Robotics/Wireless_ESTOP here].

=== Performance Tuning [Latest Version] ===
While BRUCE is in a healthy functional status, tuning some parameters can potentially improve its performance, stability, or further tailor it to your specific demands, e.g.,

* Demo (in <code>BRUCE-OP/Play/Demo/demo_macros.py</code>)

# <code>bx_offset</code> & <code>by_offset</code>: CoM velocity adjustment in moving [m]
# <code>COM_VELOCITY_LIMIT</code>: CoM velocity limit in moving [m]
# <code>px_offset</code>: CoM position adjustment in standing [m]

* OP (in <code>BRUCE-OP/Play/Walking/walking_macros.py</code>)

# <code>bx_offset</code> & <code>by_offset</code>: CoM velocity offset compensation [m]
# <code>ka</code>: x position of CoM in standing

=== Other Accessories ===

==== 1. Khadas USB Extension ====
There are two extra USB ports on the Khadas but they are covered by BRUCE's body rack so not very easy to access. For those who needs better access to these extra USB ports, we have developed an extension that shift the connection to the top of the body and exposes them better. Although one of them is USB3.0, only USB2.0 is supported by this extension for now.
{|
![[File:USB-EXT.png|none|thumb|300x300px]]
![[File:USB-EXT On BRUCE.png|none|thumb|312x312px]]
|}
Gerber files and 3D models of related parts can be downloaded in the Download section, or you can buy parts from us directly.

= Troubleshooting =

====== Using Linux Screen ======
There are multiple threads running concurrently on BRUCE, and it is achieved with multiple windows under one screen session. It is recommended to go through [https://www.gnu.org/software/screen/manual/screen.html this manual] to learn the basic operation and functions of Linux Screen.

====== Looking Into Malfunction ======
When BRUCE failed to perform a certain motion or fell, you should be able to see errors and more specific details on the failure in each thread. Follow the steps below to visit each thread for error reports:

# If operating the robot via Bluetooth remote, login via SSH to start; if already operating via SSH, jump to step 3.
# Attach to the BRUCE screen session. Use command <code>screen -ls</code> to show all opened screen sessions, find the session with BRUCE, and take note of the ID number of the session, then use <code>screen -r ID-of-BRUCE-SESSION</code> to reattach to the BRUCE session.
# Use command <code>Ctrl+A+#</code> to jump into each window of the screen session to find out the error printout of each thread. # is the number of a screen window, the range is 0~6.

For example, you might see low-level error in the TOP-LEVEL screen window, and once jumped into the LOW-LEVEL window, you might find out that the error is triggered by run-bear thread.

= Future Work =

# Add more explanation to the code, such as line by line legKF and est_KF reference. (Q1 2024)
# <s>New Body that exposes the two USB Type A ports on Khadas. (Q1 2024)</s>
#* The better solution is to design a simple adaptor PCB instead of redesigning the frame. Different groups would have very different applications thus the peripherals intended to be connected can be very different, as well as the desired mounting location, which then leads to very specific requirements of wire management. By making an adaptor board the current compact design of BRUCE can be kept while specific requirement for wire management can all be met.
# Provide a dual camera module.(Q1 2024)
# Option of a new pair of leg using KBMB as Knee Actuator for better payload capacity with the tradeoff of dynamic motions.(Q2 2024)

= Downloads =

# [https://wiki.bruce-op.com/uploads/BRUCE_V1.4_DUMMY.STEP BRUCE V1.4 3D Model]
# [[3D Printed Parts]]
# [[Simulation Files]]
# [[2D Drawings|2D drawing of Signal Cables]]
# [https://wiki.bruce-op.com/uploads/HIP_CALIBRATION_RevC.STEP Calibration Tools]
# [https://wiki.bruce-op.com/uploads/demo_controller_0.0.6.zip Binary Demo Controller]
# [[Other Accessories]]

= Reference =
Publications on BRUCE development:

# X. Zhang, "[https://escholarship.org/uc/item/9dk9r8d3 Application of Proprioception Quasi-Direct Drive Actuators on Dynamic Robotic Systems]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2019.
# Y. Liu, J. Shen, J. Zhang, X. Zhang, T. Zhu and D. Hong, "[https://ieeexplore.ieee.org/document/9811790 Design and Control of a Miniature Bipedal Robot with Proprioceptive Actuation for Dynamic Behaviors]," 2022 IEEE International Conference on Robotics and Automation (ICRA), 2022, pp. 8547-8553.
# J. Shen, J. Zhang, Y. Liu, and D. Hong, "[https://ieeexplore.ieee.org/document/10000075 Implementation of a Robust Dynamic Walking Controller on a Miniature Bipedal Robot with Proprioceptive Actuation]," 2022 IEEE-RAS International Conference on Humanoid Robots (Humanoids), 2022, pp. 39-46.
# J. Shen, "[https://escholarship.org/uc/item/52q9d7vk Locomotion Analysis and Control of a Miniature Bipedal Robot]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2022.
# J. Zhang, "[https://escholarship.org/uc/item/8002g72b Towards Application on Optimization-Based Methods for Motion Planning of Legged Robots]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2023.
# J. Zhang, J. Shen, Y. Liu and D. Hong, "[https://arxiv.org/abs/2304.00536 Design of a Jumping Control Framework with Heuristic Landing for Bipedal Robots]," 2023 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2023, pp. 8502-8509.

= Contributing to BRUCE Wiki =
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Jshen: /* Operating */

Welcome to BRUCE (Bipedal Robot Unit with Compliannce Enhanced) Wiki, where we update infomation on hardware and software of BRUCE.

= About BRUCE Project =

BRUCE is an open-platform project led by [https://www.westwoodrobotics.io/ Westwood Robotics].
It focuses on the development of a low-cost kid-size humanoid robot for research and education.

=== Licensing ===

BRUCE is dual-licensed under both commercial and open-source licenses.
The commercial BRUCE license gives you the full rights to create and distribute the platform on your own terms without any open-source license obligations.
BRUCE is also available under version 3 (or later version) of the GNU General Public License (GPL), which is ideal for use cases such as open-source projects with open-source distribution, student/academic purposes, hobby projects, internal research projects without external distribution, or other projects where all GPL obligations can be met.
Read the full text of [https://www.gnu.org/licenses/gpl-3.0.html the GNU GPL version 3] for details.

= Introduction =
=== Hardware Platform ===

[[File:BRUCE_cover_photo.jpg|thumb|Photo of BRUCE platform]]

[[File:BRUCE_schematic_diagram.jpg|thumb|BRUCE schematic diagram]]

BRUCE has a total height of 70 cm adapting an average human body proportion. It is composed of a torso, two 3-DoF arms, and two 5-DoF legs.
Each arm of BRUCE has a ball shoulder joint and a single DoF elbow joint.
Each leg of BRUCE has a spherical hip joint, a single DoF knee joint, and a single DoF ankle joint.
Each foot has a line contact with the ground.
To have better torque transparency and compliance to the unknown environment, proprioceptive actuation is equipped for each leg joint, using the [https://www.westwoodrobotics.io/koala-bear/ Koala BEAR] actuators.
Moreover, BRUCE's legs are designed to have low inertia for performing highly dynamic motions. A 2-DoF parallel actuation configuration realized by a cable-driven differential pulley system is applied to the hip joint to reduce the mass and inertia of the femur link. Meanwhile, two pairs of 4-bar linkage mechanisms are used to relocate the ankle actuator to the femur link for the light weight of the tibia link.
Finally, to ensure reliable ground contact information, a sensing foot is designed based on the working principle of an electronic switch.

BRUCE is fully untethered.
All the electronics are directly mounted onto the torso for easy installation and better weight distribution.
[https://www.khadas.com/edge2 Khadas Edge2] with RK3588S is utilized as the onboard computing resource.
A 14.8V 3000mAh Li-Ion battery is used to power the whole system with a running time of approximately 20 minutes.
For the sake of safety during operation, a wireless E-Stop built in-house is mounted onboard as well to put BEAR actuators into damping mode in emergencies.
In total, BRUCE has a net weight of around 4.8 kg.
The wiring diagrams of BRUCE are shown in the images.

=== Software Architecture ===

To make BRUCE favorable to dynamic behaviors which require fast response, the overall software framework is developed in a multithreaded environment, which includes a state estimation thread combined with robot model computation, a low-level whole-body control thread, a high-level footstep planning thread, and a top-level user input thread.
The main advantage of multithreading is that the idle time of the CPU can be kept to minimum since the waiting time for sensor response can be well distributed and utilized, which leads to faster overall execution as the CPU would have been idle if only a single thread was executed.
Data communication utilizes a custom shared memory library. All programs are implemented in Python while some parts, including kinematics, dynamics, and state estimation, are precompiled using [https://numba.pydata.org/ Numba] for acceleration.

= Working with BRUCE =

BRUCE is ready to go with the [https://github.com/Westwood-Robotics/BRUCE-OP default software] provided. Below are the detailed instructions on how to operate and maintain the platform.

=== Attention ===

* Always remember to press the '''E-STOP''' immediately in emergencies!
* Your system may need some fine tuning before it can perform perfectly, i.e., due to slight differences in joint resistance and part tolerances, systems may vary in tuning parameters.

=== Dependencies ===

* Python 3.6+ with pip, numpy, pyserial, termcolor, matplotlib, scipy, osqp, numba, dynamixel, posix_ipc
* [https://github.com/Westwood-Robotics/PyBEAR-WR PyBEAR] for communication with the BEAR actuators

=== Serial Port & MAC Address ===

Please config the serial port names (of BEAR, Dynamixel, and Pico) and MAC address of your gamepad (if applicable) in <code>BRUCE_SERIAL_PORT</code> or <code>Settings/BRUCE_macros.py</code> (line 272-283) for your BRUCE before use.

=== Allow Executing Bash/Binary File as Program ===

# Download the binary demo controller according to [https://github.com/Westwood-Robotics/BRUCE-OP/blob/main/Play/Demo/README.md README].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the following commands.
<code>
chmod +x Play/bootup.sh

chmod +x Play/bootup_gamepad.sh

chmod +x Play/sim_bootup.sh

chmod +x Play/terminate.sh

chmod +x Play/Demo/low_level-aarch64

chmod +x Play/Demo/low_level-x86_64

chmod +x Play/Demo/high_level-aarch64

chmod +x Play/Demo/high_level-x86_64

chmod +x Startups/startup_setup.sh

chmod +x Startups/usb_latency_setup.sh
</code>

=== Startup Setup Before Launch ===

BRUCE after VERSION 0.0.4 will be automatically configured at bootup with [https://help.ubuntu.com/stable/ubuntu-help/startup-applications.html.en Startup Applications].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the bash file <code>Startups/startup_setup.sh</code>.

=== Operating ===

''Quick Launch''

# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Config launch setup in <code>Play/config.py</code>.
# Run the bash file and follow the guidance <code>Play/bootup.sh</code>.
# Terminate in the end <code>Play/terminate.sh</code>.

''Full Operating''

# Make all terminals go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# In terminal 1, run USB low latency setup <code>Startups/usb_low_latency.sh</code>.
# In terminal 1, run shared memory modules <code>python3 -m Startups.memory_manager</code>.
# In terminal 1, start the Dynamixel motor thread <code>python3 -m Startups.run_dxl</code>.
# In terminal 2, start the BEAR actuator thread <code>python3 -m Startups.run_bear</code>.
# In terminal 3, initialize BRUCE <code>python3 -m Play.initialize</code> and enter <code>s</code>. If the joint angle is weird, a [[Main_Page#Calibration|calibration]] needs to be conducted.
# In terminal 3, start the sense communication thread after BRUCE can stand on the ground on its own <code>python3 -m Startups.run_sense</code>.
# In terminal 4, start the state estimation thread <code>python3 -m Startups.run_estimation</code>.
# In terminal 5, start the low-level control thread <code>python3 -m Play.Demo.low_level</code> and enter <code>y</code>.
# In terminal 6, start the high-level planning thread <code>python3 -m Play.Demo.high_level</code> and enter <code>y</code>.
# In terminal 7, start the top-level user keyboard input thread <code>python3 -m Play.Demo.top_level</code>.
# You can now play with BRUCE and remember to press the '''E-STOP''' in emergencies.
# You can recover BRUCE by releasing the '''E-STOP''' and then repeating Steps 4-10.

=== BEAR Calibration ===

[[File:BRUCE_nominal_position.jpg|thumb|BRUCE nominal position]]
[[File:BRUCE_calibration_position.jpg|thumb|BRUCE calibration position]]

The nominal posture for BRUCE is all limbs completely sprawled out as shown in the image. Note that the hip, knee, and ankle joints are aligned. You can check it with the following instructions:
# Go through Steps 1-5 in ''Full Operating''.
# In terminal 3, entering the following command <code>python3 -m Play.initialize</code> and enter <code>n</code>.

If the leg configuration is off, the related BEAR actuators need to be re-calibrated to the correct zero position with the following instructions:
# Disable the BEAR actuators by pressing and releasing the '''E-STOP'''.
# Adjust BRUCE to the calibration posture as shown in the image. Use the calibration tool if necessary.
# In terminal 3, run the calibration script <code>python3 -m Util.BEAR_calibration</code>.
# Select the actuator number that you wish to home and follow the guidance.

=== Bluetooth Gamepad ===
Beginning Jan 20, 2024, all BRUCE ships with a Bluetooth Gamepad that has a screen, with wireless ESTOP integrated. Wireless ESTOP remote will not be included in the box.

'''ATTENTION:''' Do '''NOT''' us the Wireless ESTOP remote together with this gamepad. Signals will have interference and ESTOP will malfunction.
[[File:BRUCE Gamepad.jpg|none|thumb|BRUCE BLE Gamepad]]There are two joysticks with push-buttons, two shoulder rollers with push-buttons, and 14 buttons on the remote. All buttons are labeled in the following figures:
[[File:BLE Remote.jpg|none|thumb|869x869px]]
When BRUCE is in motion, the screen is used to show the control commends and robot status:
[[File:Gamepad Legend.png|none|thumb|892x892px]]
Currently implemented Key Combinations/Commands on BRUCE-OP are:
{| class="wikitable"
|+'''BRUCE Gamepad Operation'''
!Gamepad Operation
!Function
|-
! colspan="2" | ''To Change Mode''
|-
|Start+Back
|Standing
|-
|Start+X
|Running
|-
|Start+Y
|Walking
|-
! colspan="2" | ''In Standing Mode''
|-
|Up/Down
|Longitudinal CoM Position (X)
|-
|Left Axis X
|Lateral CoM Position (Y)
|-
|Left Axis Y
|Vertical CoM Position (Z)
|-
|Right Axis X
|Body Roll (X)
|-
|Right Axis Y
|Body Pitch (Y)
|-
|Right Shoulder Roller (+/-)
|Body Yaw (Z)
|-
! colspan="2" | ''In Walking Mode''
|-
|Left Axis X
|Longitudinal CoM Velocity (X)
|-
|Left Axis Y
|Lateral CoM Velocity (Y)
|-
|Right Shoulder Roller (R+/R-)
|Body Yaw Rate (Z)
|-
|Start+Right Shoulder Roller (R+/R-)
|Right Foot Yaw (+/-)
|-
|Start+Left Shoulder Roller (L+/L-)
|Left Foot Yaw (+/-)
|-
|Start+Right/Left
|Foot Clearance (+/-)
|-
! colspan="2" | ''Other Functions''
|-
|A
|Hand Wave
|-
|Back
|Restore
|-
|Fn
|Cooling Speed (-)
|-
|Start+Fn
|Cooling Speed (+)
|-
|Left Axis Z +Right Axis Z (push down)
|Terminate (Software E-Stop)
|}

= Developers =

=== Power Hub ===
The Power Hub on BRUCE is located right above its battery, and it serves as the hub that collects and distributes signal and power for BRUCE. See the figure below for pinout definition:[[File:Power_Hub_RevB.jpg|thumb|Power Hub|none|400x400px]]

=== Khadas Edge2 ===

If you want to make further development with the onboard [https://www.khadas.com/edge2 Khadas Edge2], please refer to its online documents [https://docs.khadas.com/products/sbc/edge2/start here]. To use external keyboard and mouse, you can unplug the original 4-wire USB-C signal cable (the other one is 2-wire for power delivery) without disassembly.
[[File:Edge2.jpg|none|thumb|821x821px]]

=== BRUCE SENSE ===
BRUCE SENSE refers to the Raspberry Pi Pico on BRUCE, which is used to collect the IMU and foot contact data, as well as to control the cooling system for BEARs. Refer to the figure below for pinout definition on BRUCE SENSE:[[File:BRUCE_SENSE.jpg|thumb|BRUCE SENSE|none|450x450px]]An example of how to use it is provided (<code>BRUCE-OP/Examples/bruce_sense</code>). Users can use Arduino IDE to upload its code (<code>BRUCE-OP/Library/BRUCE_SENSE/pico/pico.ino</code>). The LED on BRUCE SENSE indicates the following status.
{| class="wikitable"
|+BRUCE SENSE LED
!Color
!Status
|-
|Green
|Initialization
|-
|White
|Idle Mode
|-
|Off
|Nominal Mode
|-
|Cyan
|Calibration Mode
|-
|Red
|Right Foot in Contact
|-
|Blue
|Left Foot in Contact
|-
|Amber
|Cooling System On
|-
|Yellow
|Delay Warning
|}

=== State Estimation ===

Two versions of state estimation are provided. One is using complementary filter solely, the details of which are described in the 4th paper of [[Main_Page#Reference|Reference]]. The other is using complementary filter for the base orientation (similar to the former) while Kalman filter for the base position and velocity, which greatly enhances the estimation performance. Interested users can refer to the document [https://wiki.bruce-op.com/uploads/BRUCE_state_estimation.pdf here].

=== IMU Calibration ===
It is recommended to calibrate the IMU bias on your BRUCE for better performance of the state estimation.
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the calibration script <code>python3 -m Util.imu_calibration</code>. Make sure the IMU is placed as flat as possible and do not move the IMU in calibration.

=== Performance Tunning [Futher Version] ===
While BRUCE is in a healthy functional status, tuning the following parameters can potentially improve its performance, stability, or further tailor it to your specific demands.

* Walking related (most parameters are included in <code>BRUCE-OP/Play/Walking/walking_macros.py</code>)

# <code>zf_l</code> & <code>zf_r</code>: swing final height [m]
# <code>bx_offset</code> & <code>by_offset</code>: velocity offset compensation [m]

* TBC

= Troubleshooting =

====== Using Linux Screen ======
There are multiple threads running simultaneously on BRUCE, and it is done via running threads in multiple windows of one screen session. It is recommended to go through [https://www.gnu.org/software/screen/manual/screen.html this manual] (https://www.gnu.org/software/screen/manual/screen.html) to learn the basic operation and functions of Linux Screen.

====== Finding The Reason of A Failure ======
When BRUCE failed to perform a certain motion or fell, you should be able to see errors and more specific details on the failure in each thread. Follow the steps below to visit each thread for error reports:

# If operating the robot via Bluetooth remote, login via SSH to start; if already operating via SSH, jump to step 3.
# Attach to the BRUCE screen session. Use command <code>screen -ls</code> to show all opened screen sessions, find the session with BRUCE, and take note of the ID number of the session, then use <code>screen -r ID-of-BRUCE-SESSION</code> to reattach to the BRUCE session.
# Use command <code>Ctrl+A+#</code> to jump into each window of the screen session to find out the error printout of each thread. # is the number of a screen window, the range is 0~6.

For example, you might see low-level error in the TOP-LEVEL screen window, and once jumped into the LOW-LEVEL window, you might find out that the error is triggered by run-bear thread.

=== Wireless ESTOP Lite ===
The Wireless ESTOP Lite system has been applied on BRUCE and other systems that are powered with BEAR actuators and has been a very handy gadget.

You can find more details about it here: https://github.com/Westwood-Robotics/Wireless_ESTOP

= Future Work =

# Add more explanation to the code, such as line by line legKF and est_KF reference. (Q1 2024)
# <s>New Body that exposes the two USB Type A ports on Khadas. (Q1 2024)</s>
#* The better solution is to design a simple adaptor PCB instead of redesigning the frame. Different groups would have very different applications thus the peripherals intended to be connected can be very different, as well as the desired mounting location, which then leads to very specific requirements of wire management. By making an adaptor board the current compact design of BRUCE can be kept while specific requirement for wire management can all be met.
# Provide a dual camera module.(Q1 2024)
# Option of a new pair of leg using KBMB as Knee Actuator for better payload capacity with the tradeoff of dynamic motions.(Q2 2024)

= Downloads =

# [https://wiki.bruce-op.com/uploads/BRUCE_V1.4_DUMMY.STEP BRUCE V1.4 3D Model]
# [[3D Printed Parts]]
# [[Simulation Files]]
# [[2D Drawings|2D drawing of Signal Cables]]
# [https://wiki.bruce-op.com/uploads/HIP_CALIBRATION_RevC.STEP Calibration Tools]
# [https://wiki.bruce-op.com/uploads/demo_controller_0.0.5.zip Binary Demo Controller]

= Reference =
Publication on BRUCE development:

# X. Zhang, "[https://escholarship.org/uc/item/9dk9r8d3 Application of Proprioception Quasi-Direct Drive Actuators on Dynamic Robotic Systems]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2019.
# Y. Liu, J. Shen, J. Zhang, X. Zhang, T. Zhu and D. Hong, "[https://ieeexplore.ieee.org/document/9811790 Design and Control of a Miniature Bipedal Robot with Proprioceptive Actuation for Dynamic Behaviors]," 2022 IEEE International Conference on Robotics and Automation (ICRA), 2022, pp. 8547-8553.
# J. Shen, J. Zhang, Y. Liu, and D. Hong, "[https://ieeexplore.ieee.org/document/10000075 Implementation of a Robust Dynamic Walking Controller on a Miniature Bipedal Robot with Proprioceptive Actuation]," 2022 IEEE-RAS International Conference on Humanoid Robots (Humanoids), 2022, pp. 39-46.
# J. Shen, "[https://escholarship.org/uc/item/52q9d7vk Locomotion Analysis and Control of a Miniature Bipedal Robot]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2022.
# J. Zhang, "[https://escholarship.org/uc/item/8002g72b Towards Application on Optimization-Based Methods for Motion Planning of Legged Robots]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2023.
# J. Zhang, J. Shen, Y. Liu and D. Hong, "[https://arxiv.org/abs/2304.00536 Design of a Jumping Control Framework with Heuristic Landing for Bipedal Robots]," 2023 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2023, pp. TBD.

= Contributing to BRUCE Wiki =
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Main Page

2024-03-14T09:13:04Z

Jshen: /* Operating */

Welcome to BRUCE (Bipedal Robot Unit with Compliannce Enhanced) Wiki, where we update infomation on hardware and software of BRUCE.

= About BRUCE Project =

BRUCE is an open-platform project led by [https://www.westwoodrobotics.io/ Westwood Robotics].
It focuses on the development of a low-cost kid-size humanoid robot for research and education.

=== Licensing ===

BRUCE is dual-licensed under both commercial and open-source licenses.
The commercial BRUCE license gives you the full rights to create and distribute the platform on your own terms without any open-source license obligations.
BRUCE is also available under version 3 (or later version) of the GNU General Public License (GPL), which is ideal for use cases such as open-source projects with open-source distribution, student/academic purposes, hobby projects, internal research projects without external distribution, or other projects where all GPL obligations can be met.
Read the full text of [https://www.gnu.org/licenses/gpl-3.0.html the GNU GPL version 3] for details.

= Introduction =
=== Hardware Platform ===

[[File:BRUCE_cover_photo.jpg|thumb|Photo of BRUCE platform]]

[[File:BRUCE_schematic_diagram.jpg|thumb|BRUCE schematic diagram]]

BRUCE has a total height of 70 cm adapting an average human body proportion. It is composed of a torso, two 3-DoF arms, and two 5-DoF legs.
Each arm of BRUCE has a ball shoulder joint and a single DoF elbow joint.
Each leg of BRUCE has a spherical hip joint, a single DoF knee joint, and a single DoF ankle joint.
Each foot has a line contact with the ground.
To have better torque transparency and compliance to the unknown environment, proprioceptive actuation is equipped for each leg joint, using the [https://www.westwoodrobotics.io/koala-bear/ Koala BEAR] actuators.
Moreover, BRUCE's legs are designed to have low inertia for performing highly dynamic motions. A 2-DoF parallel actuation configuration realized by a cable-driven differential pulley system is applied to the hip joint to reduce the mass and inertia of the femur link. Meanwhile, two pairs of 4-bar linkage mechanisms are used to relocate the ankle actuator to the femur link for the light weight of the tibia link.
Finally, to ensure reliable ground contact information, a sensing foot is designed based on the working principle of an electronic switch.

BRUCE is fully untethered.
All the electronics are directly mounted onto the torso for easy installation and better weight distribution.
[https://www.khadas.com/edge2 Khadas Edge2] with RK3588S is utilized as the onboard computing resource.
A 14.8V 3000mAh Li-Ion battery is used to power the whole system with a running time of approximately 20 minutes.
For the sake of safety during operation, a wireless E-Stop built in-house is mounted onboard as well to put BEAR actuators into damping mode in emergencies.
In total, BRUCE has a net weight of around 4.8 kg.
The wiring diagrams of BRUCE are shown in the images.

=== Software Architecture ===

To make BRUCE favorable to dynamic behaviors which require fast response, the overall software framework is developed in a multithreaded environment, which includes a state estimation thread combined with robot model computation, a low-level whole-body control thread, a high-level footstep planning thread, and a top-level user input thread.
The main advantage of multithreading is that the idle time of the CPU can be kept to minimum since the waiting time for sensor response can be well distributed and utilized, which leads to faster overall execution as the CPU would have been idle if only a single thread was executed.
Data communication utilizes a custom shared memory library. All programs are implemented in Python while some parts, including kinematics, dynamics, and state estimation, are precompiled using [https://numba.pydata.org/ Numba] for acceleration.

= Working with BRUCE =

BRUCE is ready to go with the [https://github.com/Westwood-Robotics/BRUCE-OP default software] provided. Below are the detailed instructions on how to operate and maintain the platform.

=== Attention ===

* Always remember to press the '''E-STOP''' immediately in emergencies!
* Your system may need some fine tuning before it can perform perfectly, i.e., due to slight differences in joint resistance and part tolerances, systems may vary in tuning parameters.

=== Dependencies ===

* Python 3.6+ with pip, numpy, pyserial, termcolor, matplotlib, scipy, osqp, numba, dynamixel, posix_ipc
* [https://github.com/Westwood-Robotics/PyBEAR-WR PyBEAR] for communication with the BEAR actuators

=== Serial Port & MAC Address ===

Please config the serial port names (of BEAR, Dynamixel, and Pico) and MAC address of your gamepad (if applicable) in <code>BRUCE_SERIAL_PORT</code> or <code>Settings/BRUCE_macros.py</code> (line 272-283) for your BRUCE before use.

=== Allow Executing Bash/Binary File as Program ===

# Download the binary demo controller according to [https://github.com/Westwood-Robotics/BRUCE-OP/blob/main/Play/Demo/README.md README].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the following commands.
<code>
chmod +x Play/bootup.sh

chmod +x Play/bootup_gamepad.sh

chmod +x Play/sim_bootup.sh

chmod +x Play/terminate.sh

chmod +x Play/Demo/low_level-aarch64

chmod +x Play/Demo/low_level-x86_64

chmod +x Play/Demo/high_level-aarch64

chmod +x Play/Demo/high_level-x86_64

chmod +x Startups/startup_setup.sh

chmod +x Startups/usb_latency_setup.sh
</code>

=== Startup Setup Before Launch ===

BRUCE after VERSION 0.0.4 will be automatically configured at bootup with [https://help.ubuntu.com/stable/ubuntu-help/startup-applications.html.en Startup Applications].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the bash file <code>Startups/startup_setup.sh</code>.

=== Operating ===

''Quick Launch''

# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Config launch setup in <code>Play/config.py</code>.
# Run the bash file and follow the guidance <code>Play/bootup.sh</code>.
# Terminate in the end <code>Play/terminate.sh</code>.

''Full Operating''

# Make all terminals go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# In terminal 1, run USB low latency setup <code>Startups/usb_low_latency.sh</code>.
# In terminal 1, run shared memory modules <code>python3 -m Startups.memory_manager</code>.
# In terminal 1, start the Dynamixel motor thread afterwards <code>python3 -m Startups.run_dxl</code>.
# In terminal 2, start the BEAR actuator thread <code>python3 -m Startups.run_bear</code>.
# In terminal 3, initialize BRUCE <code>python3 -m Play.initialize</code> and enter <code>s</code>. If the joint angle is weird, a [[Main_Page#Calibration|calibration]] needs to be conducted.
# In terminal 3, start the sense communication thread after BRUCE can stand on the ground on its own <code>python3 -m Startups.run_sense</code>.
# In terminal 4, start the state estimation thread <code>python3 -m Startups.run_estimation</code>.
# In terminal 5, start the low-level control thread <code>python3 -m Play.Demo.low_level</code> and enter <code>y</code>.
# In terminal 6, start the high-level planning thread <code>python3 -m Play.Demo.high_level</code> and enter <code>y</code>.
# In terminal 7, start the top-level user keyboard input thread <code>python3 -m Play.Demo.top_level</code>.
# You can now play with BRUCE and remember to press the '''E-STOP''' in emergencies.
# You can recover BRUCE by releasing the '''E-STOP''' and then repeating Steps 4-10.

=== BEAR Calibration ===

[[File:BRUCE_nominal_position.jpg|thumb|BRUCE nominal position]]
[[File:BRUCE_calibration_position.jpg|thumb|BRUCE calibration position]]

The nominal posture for BRUCE is all limbs completely sprawled out as shown in the image. Note that the hip, knee, and ankle joints are aligned. You can check it with the following instructions:
# Go through Steps 1-5 in ''Full Operating''.
# In terminal 3, entering the following command <code>python3 -m Play.initialize</code> and enter <code>n</code>.

If the leg configuration is off, the related BEAR actuators need to be re-calibrated to the correct zero position with the following instructions:
# Disable the BEAR actuators by pressing and releasing the '''E-STOP'''.
# Adjust BRUCE to the calibration posture as shown in the image. Use the calibration tool if necessary.
# In terminal 3, run the calibration script <code>python3 -m Util.BEAR_calibration</code>.
# Select the actuator number that you wish to home and follow the guidance.

=== Bluetooth Gamepad ===
Beginning Jan 20, 2024, all BRUCE ships with a Bluetooth Gamepad that has a screen, with wireless ESTOP integrated. Wireless ESTOP remote will not be included in the box.

'''ATTENTION:''' Do '''NOT''' us the Wireless ESTOP remote together with this gamepad. Signals will have interference and ESTOP will malfunction.
[[File:BRUCE Gamepad.jpg|none|thumb|BRUCE BLE Gamepad]]There are two joysticks with push-buttons, two shoulder rollers with push-buttons, and 14 buttons on the remote. All buttons are labeled in the following figures:
[[File:BLE Remote.jpg|none|thumb|869x869px]]
When BRUCE is in motion, the screen is used to show the control commends and robot status:
[[File:Gamepad Legend.png|none|thumb|892x892px]]
Currently implemented Key Combinations/Commands on BRUCE-OP are:
{| class="wikitable"
|+'''BRUCE Gamepad Operation'''
!Gamepad Operation
!Function
|-
! colspan="2" | ''To Change Mode''
|-
|Start+Back
|Standing
|-
|Start+X
|Running
|-
|Start+Y
|Walking
|-
! colspan="2" | ''In Standing Mode''
|-
|Up/Down
|Longitudinal CoM Position (X)
|-
|Left Axis X
|Lateral CoM Position (Y)
|-
|Left Axis Y
|Vertical CoM Position (Z)
|-
|Right Axis X
|Body Roll (X)
|-
|Right Axis Y
|Body Pitch (Y)
|-
|Right Shoulder Roller (+/-)
|Body Yaw (Z)
|-
! colspan="2" | ''In Walking Mode''
|-
|Left Axis X
|Longitudinal CoM Velocity (X)
|-
|Left Axis Y
|Lateral CoM Velocity (Y)
|-
|Right Shoulder Roller (R+/R-)
|Body Yaw Rate (Z)
|-
|Start+Right Shoulder Roller (R+/R-)
|Right Foot Yaw (+/-)
|-
|Start+Left Shoulder Roller (L+/L-)
|Left Foot Yaw (+/-)
|-
|Start+Right/Left
|Foot Clearance (+/-)
|-
! colspan="2" | ''Other Functions''
|-
|A
|Hand Wave
|-
|Back
|Restore
|-
|Fn
|Cooling Speed (-)
|-
|Start+Fn
|Cooling Speed (+)
|-
|Left Axis Z +Right Axis Z (push down)
|Terminate (Software E-Stop)
|}

= Developers =

=== Power Hub ===
The Power Hub on BRUCE is located right above its battery, and it serves as the hub that collects and distributes signal and power for BRUCE. See the figure below for pinout definition:[[File:Power_Hub_RevB.jpg|thumb|Power Hub|none|400x400px]]

=== Khadas Edge2 ===

If you want to make further development with the onboard [https://www.khadas.com/edge2 Khadas Edge2], please refer to its online documents [https://docs.khadas.com/products/sbc/edge2/start here]. To use external keyboard and mouse, you can unplug the original 4-wire USB-C signal cable (the other one is 2-wire for power delivery) without disassembly.
[[File:Edge2.jpg|none|thumb|821x821px]]

=== BRUCE SENSE ===
BRUCE SENSE refers to the Raspberry Pi Pico on BRUCE, which is used to collect the IMU and foot contact data, as well as to control the cooling system for BEARs. Refer to the figure below for pinout definition on BRUCE SENSE:[[File:BRUCE_SENSE.jpg|thumb|BRUCE SENSE|none|450x450px]]An example of how to use it is provided (<code>BRUCE-OP/Examples/bruce_sense</code>). Users can use Arduino IDE to upload its code (<code>BRUCE-OP/Library/BRUCE_SENSE/pico/pico.ino</code>). The LED on BRUCE SENSE indicates the following status.
{| class="wikitable"
|+BRUCE SENSE LED
!Color
!Status
|-
|Green
|Initialization
|-
|White
|Idle Mode
|-
|Off
|Nominal Mode
|-
|Cyan
|Calibration Mode
|-
|Red
|Right Foot in Contact
|-
|Blue
|Left Foot in Contact
|-
|Amber
|Cooling System On
|-
|Yellow
|Delay Warning
|}

=== State Estimation ===

Two versions of state estimation are provided. One is using complementary filter solely, the details of which are described in the 4th paper of [[Main_Page#Reference|Reference]]. The other is using complementary filter for the base orientation (similar to the former) while Kalman filter for the base position and velocity, which greatly enhances the estimation performance. Interested users can refer to the document [https://wiki.bruce-op.com/uploads/BRUCE_state_estimation.pdf here].

=== IMU Calibration ===
It is recommended to calibrate the IMU bias on your BRUCE for better performance of the state estimation.
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the calibration script <code>python3 -m Util.imu_calibration</code>. Make sure the IMU is placed as flat as possible and do not move the IMU in calibration.

=== Performance Tunning [Futher Version] ===
While BRUCE is in a healthy functional status, tuning the following parameters can potentially improve its performance, stability, or further tailor it to your specific demands.

* Walking related (most parameters are included in <code>BRUCE-OP/Play/Walking/walking_macros.py</code>)

# <code>zf_l</code> & <code>zf_r</code>: swing final height [m]
# <code>bx_offset</code> & <code>by_offset</code>: velocity offset compensation [m]

* TBC

= Troubleshooting =

====== Using Linux Screen ======
There are multiple threads running simultaneously on BRUCE, and it is done via running threads in multiple windows of one screen session. It is recommended to go through [https://www.gnu.org/software/screen/manual/screen.html this manual] (https://www.gnu.org/software/screen/manual/screen.html) to learn the basic operation and functions of Linux Screen.

====== Finding The Reason of A Failure ======
When BRUCE failed to perform a certain motion or fell, you should be able to see errors and more specific details on the failure in each thread. Follow the steps below to visit each thread for error reports:

# If operating the robot via Bluetooth remote, login via SSH to start; if already operating via SSH, jump to step 3.
# Attach to the BRUCE screen session. Use command <code>screen -ls</code> to show all opened screen sessions, find the session with BRUCE, and take note of the ID number of the session, then use <code>screen -r ID-of-BRUCE-SESSION</code> to reattach to the BRUCE session.
# Use command <code>Ctrl+A+#</code> to jump into each window of the screen session to find out the error printout of each thread. # is the number of a screen window, the range is 0~6.

For example, you might see low-level error in the TOP-LEVEL screen window, and once jumped into the LOW-LEVEL window, you might find out that the error is triggered by run-bear thread.

=== Wireless ESTOP Lite ===
The Wireless ESTOP Lite system has been applied on BRUCE and other systems that are powered with BEAR actuators and has been a very handy gadget.

You can find more details about it here: https://github.com/Westwood-Robotics/Wireless_ESTOP

= Future Work =

# Add more explanation to the code, such as line by line legKF and est_KF reference. (Q1 2024)
# <s>New Body that exposes the two USB Type A ports on Khadas. (Q1 2024)</s>
#* The better solution is to design a simple adaptor PCB instead of redesigning the frame. Different groups would have very different applications thus the peripherals intended to be connected can be very different, as well as the desired mounting location, which then leads to very specific requirements of wire management. By making an adaptor board the current compact design of BRUCE can be kept while specific requirement for wire management can all be met.
# Provide a dual camera module.(Q1 2024)
# Option of a new pair of leg using KBMB as Knee Actuator for better payload capacity with the tradeoff of dynamic motions.(Q2 2024)

= Downloads =

# [https://wiki.bruce-op.com/uploads/BRUCE_V1.4_DUMMY.STEP BRUCE V1.4 3D Model]
# [[3D Printed Parts]]
# [[Simulation Files]]
# [[2D Drawings|2D drawing of Signal Cables]]
# [https://wiki.bruce-op.com/uploads/HIP_CALIBRATION_RevC.STEP Calibration Tools]
# [https://wiki.bruce-op.com/uploads/demo_controller_0.0.5.zip Binary Demo Controller]

= Reference =
Publication on BRUCE development:

# X. Zhang, "[https://escholarship.org/uc/item/9dk9r8d3 Application of Proprioception Quasi-Direct Drive Actuators on Dynamic Robotic Systems]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2019.
# Y. Liu, J. Shen, J. Zhang, X. Zhang, T. Zhu and D. Hong, "[https://ieeexplore.ieee.org/document/9811790 Design and Control of a Miniature Bipedal Robot with Proprioceptive Actuation for Dynamic Behaviors]," 2022 IEEE International Conference on Robotics and Automation (ICRA), 2022, pp. 8547-8553.
# J. Shen, J. Zhang, Y. Liu, and D. Hong, "[https://ieeexplore.ieee.org/document/10000075 Implementation of a Robust Dynamic Walking Controller on a Miniature Bipedal Robot with Proprioceptive Actuation]," 2022 IEEE-RAS International Conference on Humanoid Robots (Humanoids), 2022, pp. 39-46.
# J. Shen, "[https://escholarship.org/uc/item/52q9d7vk Locomotion Analysis and Control of a Miniature Bipedal Robot]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2022.
# J. Zhang, "[https://escholarship.org/uc/item/8002g72b Towards Application on Optimization-Based Methods for Motion Planning of Legged Robots]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2023.
# J. Zhang, J. Shen, Y. Liu and D. Hong, "[https://arxiv.org/abs/2304.00536 Design of a Jumping Control Framework with Heuristic Landing for Bipedal Robots]," 2023 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2023, pp. TBD.

= Contributing to BRUCE Wiki =
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Main Page

2024-03-14T09:12:15Z

Jshen: /* Operating */

Welcome to BRUCE (Bipedal Robot Unit with Compliannce Enhanced) Wiki, where we update infomation on hardware and software of BRUCE.

= About BRUCE Project =

BRUCE is an open-platform project led by [https://www.westwoodrobotics.io/ Westwood Robotics].
It focuses on the development of a low-cost kid-size humanoid robot for research and education.

=== Licensing ===

BRUCE is dual-licensed under both commercial and open-source licenses.
The commercial BRUCE license gives you the full rights to create and distribute the platform on your own terms without any open-source license obligations.
BRUCE is also available under version 3 (or later version) of the GNU General Public License (GPL), which is ideal for use cases such as open-source projects with open-source distribution, student/academic purposes, hobby projects, internal research projects without external distribution, or other projects where all GPL obligations can be met.
Read the full text of [https://www.gnu.org/licenses/gpl-3.0.html the GNU GPL version 3] for details.

= Introduction =
=== Hardware Platform ===

[[File:BRUCE_cover_photo.jpg|thumb|Photo of BRUCE platform]]

[[File:BRUCE_schematic_diagram.jpg|thumb|BRUCE schematic diagram]]

BRUCE has a total height of 70 cm adapting an average human body proportion. It is composed of a torso, two 3-DoF arms, and two 5-DoF legs.
Each arm of BRUCE has a ball shoulder joint and a single DoF elbow joint.
Each leg of BRUCE has a spherical hip joint, a single DoF knee joint, and a single DoF ankle joint.
Each foot has a line contact with the ground.
To have better torque transparency and compliance to the unknown environment, proprioceptive actuation is equipped for each leg joint, using the [https://www.westwoodrobotics.io/koala-bear/ Koala BEAR] actuators.
Moreover, BRUCE's legs are designed to have low inertia for performing highly dynamic motions. A 2-DoF parallel actuation configuration realized by a cable-driven differential pulley system is applied to the hip joint to reduce the mass and inertia of the femur link. Meanwhile, two pairs of 4-bar linkage mechanisms are used to relocate the ankle actuator to the femur link for the light weight of the tibia link.
Finally, to ensure reliable ground contact information, a sensing foot is designed based on the working principle of an electronic switch.

BRUCE is fully untethered.
All the electronics are directly mounted onto the torso for easy installation and better weight distribution.
[https://www.khadas.com/edge2 Khadas Edge2] with RK3588S is utilized as the onboard computing resource.
A 14.8V 3000mAh Li-Ion battery is used to power the whole system with a running time of approximately 20 minutes.
For the sake of safety during operation, a wireless E-Stop built in-house is mounted onboard as well to put BEAR actuators into damping mode in emergencies.
In total, BRUCE has a net weight of around 4.8 kg.
The wiring diagrams of BRUCE are shown in the images.

=== Software Architecture ===

To make BRUCE favorable to dynamic behaviors which require fast response, the overall software framework is developed in a multithreaded environment, which includes a state estimation thread combined with robot model computation, a low-level whole-body control thread, a high-level footstep planning thread, and a top-level user input thread.
The main advantage of multithreading is that the idle time of the CPU can be kept to minimum since the waiting time for sensor response can be well distributed and utilized, which leads to faster overall execution as the CPU would have been idle if only a single thread was executed.
Data communication utilizes a custom shared memory library. All programs are implemented in Python while some parts, including kinematics, dynamics, and state estimation, are precompiled using [https://numba.pydata.org/ Numba] for acceleration.

= Working with BRUCE =

BRUCE is ready to go with the [https://github.com/Westwood-Robotics/BRUCE-OP default software] provided. Below are the detailed instructions on how to operate and maintain the platform.

=== Attention ===

* Always remember to press the '''E-STOP''' immediately in emergencies!
* Your system may need some fine tuning before it can perform perfectly, i.e., due to slight differences in joint resistance and part tolerances, systems may vary in tuning parameters.

=== Dependencies ===

* Python 3.6+ with pip, numpy, pyserial, termcolor, matplotlib, scipy, osqp, numba, dynamixel, posix_ipc
* [https://github.com/Westwood-Robotics/PyBEAR-WR PyBEAR] for communication with the BEAR actuators

=== Serial Port & MAC Address ===

Please config the serial port names (of BEAR, Dynamixel, and Pico) and MAC address of your gamepad (if applicable) in <code>BRUCE_SERIAL_PORT</code> or <code>Settings/BRUCE_macros.py</code> (line 272-283) for your BRUCE before use.

=== Allow Executing Bash/Binary File as Program ===

# Download the binary demo controller according to [https://github.com/Westwood-Robotics/BRUCE-OP/blob/main/Play/Demo/README.md README].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the following commands.
<code>
chmod +x Play/bootup.sh

chmod +x Play/bootup_gamepad.sh

chmod +x Play/sim_bootup.sh

chmod +x Play/terminate.sh

chmod +x Play/Demo/low_level-aarch64

chmod +x Play/Demo/low_level-x86_64

chmod +x Play/Demo/high_level-aarch64

chmod +x Play/Demo/high_level-x86_64

chmod +x Startups/startup_setup.sh

chmod +x Startups/usb_latency_setup.sh
</code>

=== Startup Setup Before Launch ===

BRUCE after VERSION 0.0.4 will be automatically configured at bootup with [https://help.ubuntu.com/stable/ubuntu-help/startup-applications.html.en Startup Applications].
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the bash file <code>Startups/startup_setup.sh</code>.

=== Operating ===

''Quick Launch''

# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Config launch setup in <code>Play/config.py</code>.
# Run the bash file and follow the guidance <code>Play/bootup.sh</code>.
# Terminate in the end <code>Play/terminate.sh</code>.

''Full Operating''

# Make all terminals go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# In terminal 1, run USB low latency setup <code>Startups/usb_low_latency.sh</code>.
# In terminal 1, Run shared memory modules <code>python3 -m Startups.memory_manager</code>.
# In terminal 1, Start Dynamixel motor thread afterwards <code>python3 -m Startups.run_dxl</code>.
# In terminal 2, start BEAR actuator thread <code>python3 -m Startups.run_bear</code>.
# In terminal 3, initialize BRUCE <code>python3 -m Play.initialize</code> and enter <code>s</code>. If the joint angle is weird, a [[Main_Page#Calibration|calibration]] needs to be conducted.
# In terminal 3, start the sense communication thread after BRUCE can stand on the ground on its own <code>python3 -m Startups.run_sense</code>.
# In terminal 4, start the state estimation thread <code>python3 -m Startups.run_estimation</code>.
# In terminal 5, start the low-level control thread <code>python3 -m Play.Walking.low_level</code> and enter <code>y</code>.
# In terminal 6, start the high-level planning thread <code>python3 -m Play.Walking.high_level</code> and enter <code>y</code>.
# In terminal 7, start the top-level user keyboard input thread <code>python3 -m Play.Walking.top_level</code>.
# You can now play with BRUCE and remember to press the '''E-STOP''' in emergencies.
# You can recover BRUCE by releasing the '''E-STOP''' and then repeating Steps 4-10.

=== BEAR Calibration ===

[[File:BRUCE_nominal_position.jpg|thumb|BRUCE nominal position]]
[[File:BRUCE_calibration_position.jpg|thumb|BRUCE calibration position]]

The nominal posture for BRUCE is all limbs completely sprawled out as shown in the image. Note that the hip, knee, and ankle joints are aligned. You can check it with the following instructions:
# Go through Steps 1-5 in ''Full Operating''.
# In terminal 3, entering the following command <code>python3 -m Play.initialize</code> and enter <code>n</code>.

If the leg configuration is off, the related BEAR actuators need to be re-calibrated to the correct zero position with the following instructions:
# Disable the BEAR actuators by pressing and releasing the '''E-STOP'''.
# Adjust BRUCE to the calibration posture as shown in the image. Use the calibration tool if necessary.
# In terminal 3, run the calibration script <code>python3 -m Util.BEAR_calibration</code>.
# Select the actuator number that you wish to home and follow the guidance.

=== Bluetooth Gamepad ===
Beginning Jan 20, 2024, all BRUCE ships with a Bluetooth Gamepad that has a screen, with wireless ESTOP integrated. Wireless ESTOP remote will not be included in the box.

'''ATTENTION:''' Do '''NOT''' us the Wireless ESTOP remote together with this gamepad. Signals will have interference and ESTOP will malfunction.
[[File:BRUCE Gamepad.jpg|none|thumb|BRUCE BLE Gamepad]]There are two joysticks with push-buttons, two shoulder rollers with push-buttons, and 14 buttons on the remote. All buttons are labeled in the following figures:
[[File:BLE Remote.jpg|none|thumb|869x869px]]
When BRUCE is in motion, the screen is used to show the control commends and robot status:
[[File:Gamepad Legend.png|none|thumb|892x892px]]
Currently implemented Key Combinations/Commands on BRUCE-OP are:
{| class="wikitable"
|+'''BRUCE Gamepad Operation'''
!Gamepad Operation
!Function
|-
! colspan="2" | ''To Change Mode''
|-
|Start+Back
|Standing
|-
|Start+X
|Running
|-
|Start+Y
|Walking
|-
! colspan="2" | ''In Standing Mode''
|-
|Up/Down
|Longitudinal CoM Position (X)
|-
|Left Axis X
|Lateral CoM Position (Y)
|-
|Left Axis Y
|Vertical CoM Position (Z)
|-
|Right Axis X
|Body Roll (X)
|-
|Right Axis Y
|Body Pitch (Y)
|-
|Right Shoulder Roller (+/-)
|Body Yaw (Z)
|-
! colspan="2" | ''In Walking Mode''
|-
|Left Axis X
|Longitudinal CoM Velocity (X)
|-
|Left Axis Y
|Lateral CoM Velocity (Y)
|-
|Right Shoulder Roller (R+/R-)
|Body Yaw Rate (Z)
|-
|Start+Right Shoulder Roller (R+/R-)
|Right Foot Yaw (+/-)
|-
|Start+Left Shoulder Roller (L+/L-)
|Left Foot Yaw (+/-)
|-
|Start+Right/Left
|Foot Clearance (+/-)
|-
! colspan="2" | ''Other Functions''
|-
|A
|Hand Wave
|-
|Back
|Restore
|-
|Fn
|Cooling Speed (-)
|-
|Start+Fn
|Cooling Speed (+)
|-
|Left Axis Z +Right Axis Z (push down)
|Terminate (Software E-Stop)
|}

= Developers =

=== Power Hub ===
The Power Hub on BRUCE is located right above its battery, and it serves as the hub that collects and distributes signal and power for BRUCE. See the figure below for pinout definition:[[File:Power_Hub_RevB.jpg|thumb|Power Hub|none|400x400px]]

=== Khadas Edge2 ===

If you want to make further development with the onboard [https://www.khadas.com/edge2 Khadas Edge2], please refer to its online documents [https://docs.khadas.com/products/sbc/edge2/start here]. To use external keyboard and mouse, you can unplug the original 4-wire USB-C signal cable (the other one is 2-wire for power delivery) without disassembly.
[[File:Edge2.jpg|none|thumb|821x821px]]

=== BRUCE SENSE ===
BRUCE SENSE refers to the Raspberry Pi Pico on BRUCE, which is used to collect the IMU and foot contact data, as well as to control the cooling system for BEARs. Refer to the figure below for pinout definition on BRUCE SENSE:[[File:BRUCE_SENSE.jpg|thumb|BRUCE SENSE|none|450x450px]]An example of how to use it is provided (<code>BRUCE-OP/Examples/bruce_sense</code>). Users can use Arduino IDE to upload its code (<code>BRUCE-OP/Library/BRUCE_SENSE/pico/pico.ino</code>). The LED on BRUCE SENSE indicates the following status.
{| class="wikitable"
|+BRUCE SENSE LED
!Color
!Status
|-
|Green
|Initialization
|-
|White
|Idle Mode
|-
|Off
|Nominal Mode
|-
|Cyan
|Calibration Mode
|-
|Red
|Right Foot in Contact
|-
|Blue
|Left Foot in Contact
|-
|Amber
|Cooling System On
|-
|Yellow
|Delay Warning
|}

=== State Estimation ===

Two versions of state estimation are provided. One is using complementary filter solely, the details of which are described in the 4th paper of [[Main_Page#Reference|Reference]]. The other is using complementary filter for the base orientation (similar to the former) while Kalman filter for the base position and velocity, which greatly enhances the estimation performance. Interested users can refer to the document [https://wiki.bruce-op.com/uploads/BRUCE_state_estimation.pdf here].

=== IMU Calibration ===
It is recommended to calibrate the IMU bias on your BRUCE for better performance of the state estimation.
# Go to BRUCE-OP folder <code>cd BRUCE/BRUCE-OP</code>.
# Run the calibration script <code>python3 -m Util.imu_calibration</code>. Make sure the IMU is placed as flat as possible and do not move the IMU in calibration.

=== Performance Tunning [Futher Version] ===
While BRUCE is in a healthy functional status, tuning the following parameters can potentially improve its performance, stability, or further tailor it to your specific demands.

* Walking related (most parameters are included in <code>BRUCE-OP/Play/Walking/walking_macros.py</code>)

# <code>zf_l</code> & <code>zf_r</code>: swing final height [m]
# <code>bx_offset</code> & <code>by_offset</code>: velocity offset compensation [m]

* TBC

= Troubleshooting =

====== Using Linux Screen ======
There are multiple threads running simultaneously on BRUCE, and it is done via running threads in multiple windows of one screen session. It is recommended to go through [https://www.gnu.org/software/screen/manual/screen.html this manual] (https://www.gnu.org/software/screen/manual/screen.html) to learn the basic operation and functions of Linux Screen.

====== Finding The Reason of A Failure ======
When BRUCE failed to perform a certain motion or fell, you should be able to see errors and more specific details on the failure in each thread. Follow the steps below to visit each thread for error reports:

# If operating the robot via Bluetooth remote, login via SSH to start; if already operating via SSH, jump to step 3.
# Attach to the BRUCE screen session. Use command <code>screen -ls</code> to show all opened screen sessions, find the session with BRUCE, and take note of the ID number of the session, then use <code>screen -r ID-of-BRUCE-SESSION</code> to reattach to the BRUCE session.
# Use command <code>Ctrl+A+#</code> to jump into each window of the screen session to find out the error printout of each thread. # is the number of a screen window, the range is 0~6.

For example, you might see low-level error in the TOP-LEVEL screen window, and once jumped into the LOW-LEVEL window, you might find out that the error is triggered by run-bear thread.

=== Wireless ESTOP Lite ===
The Wireless ESTOP Lite system has been applied on BRUCE and other systems that are powered with BEAR actuators and has been a very handy gadget.

You can find more details about it here: https://github.com/Westwood-Robotics/Wireless_ESTOP

= Future Work =

# Add more explanation to the code, such as line by line legKF and est_KF reference. (Q1 2024)
# <s>New Body that exposes the two USB Type A ports on Khadas. (Q1 2024)</s>
#* The better solution is to design a simple adaptor PCB instead of redesigning the frame. Different groups would have very different applications thus the peripherals intended to be connected can be very different, as well as the desired mounting location, which then leads to very specific requirements of wire management. By making an adaptor board the current compact design of BRUCE can be kept while specific requirement for wire management can all be met.
# Provide a dual camera module.(Q1 2024)
# Option of a new pair of leg using KBMB as Knee Actuator for better payload capacity with the tradeoff of dynamic motions.(Q2 2024)

= Downloads =

# [https://wiki.bruce-op.com/uploads/BRUCE_V1.4_DUMMY.STEP BRUCE V1.4 3D Model]
# [[3D Printed Parts]]
# [[Simulation Files]]
# [[2D Drawings|2D drawing of Signal Cables]]
# [https://wiki.bruce-op.com/uploads/HIP_CALIBRATION_RevC.STEP Calibration Tools]
# [https://wiki.bruce-op.com/uploads/demo_controller_0.0.5.zip Binary Demo Controller]

= Reference =
Publication on BRUCE development:

# X. Zhang, "[https://escholarship.org/uc/item/9dk9r8d3 Application of Proprioception Quasi-Direct Drive Actuators on Dynamic Robotic Systems]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2019.
# Y. Liu, J. Shen, J. Zhang, X. Zhang, T. Zhu and D. Hong, "[https://ieeexplore.ieee.org/document/9811790 Design and Control of a Miniature Bipedal Robot with Proprioceptive Actuation for Dynamic Behaviors]," 2022 IEEE International Conference on Robotics and Automation (ICRA), 2022, pp. 8547-8553.
# J. Shen, J. Zhang, Y. Liu, and D. Hong, "[https://ieeexplore.ieee.org/document/10000075 Implementation of a Robust Dynamic Walking Controller on a Miniature Bipedal Robot with Proprioceptive Actuation]," 2022 IEEE-RAS International Conference on Humanoid Robots (Humanoids), 2022, pp. 39-46.
# J. Shen, "[https://escholarship.org/uc/item/52q9d7vk Locomotion Analysis and Control of a Miniature Bipedal Robot]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2022.
# J. Zhang, "[https://escholarship.org/uc/item/8002g72b Towards Application on Optimization-Based Methods for Motion Planning of Legged Robots]," Ph.D. Dissertation, University of California, Los Angeles (UCLA), 2023.
# J. Zhang, J. Shen, Y. Liu and D. Hong, "[https://arxiv.org/abs/2304.00536 Design of a Jumping Control Framework with Heuristic Landing for Bipedal Robots]," 2023 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2023, pp. TBD.

= Contributing to BRUCE Wiki =
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]