Python Package

A clean, powerful Python Package for controlling Hackerbot — drive, navigate, move the head, and manipulate objects with ease. Designed for developers, educators, and hobbyists, the SDK abstracts away

---

⚡ Quick Start

SSH into the raspberry pi or open a VNC viewer, then install the official python package:

pip install hackerbot

Or upgrade the existing package:

pip install --upgrade hackerbot

Then, run python3 to open up Python interactive shell and copy and paste the following:

from hackerbot import Hackerbot

bot = Hackerbot()

bot.base.drive(0, 65)
bot.base.drive(200, 0)

You should see your Hackerbot leave the charger and move in the opposite direction.

bot.head.look(180, 250, 70)

Now your robot should move your head and look up at you!

bot.arm.move_joints(0,0,0,0,0,0,10)

You should see your elephant arm moving to a straight up position.

bot.base.destroy(auto_dock=True)

Safely clean up and your hackerbot will go back to the charger. Once the destroy is called, you need to create a new hackerbot instance to perform new actions.

---

🚀 Function Overview

• Hackerbot(verbose_mode=True)

  • verbose_mode: (bool) Enables detailed error and warning logs during runtime.

---

🧠 Core System

• Hackerbot.core.ping() Returns wire connections to hardware devices.

• Hackerbot.core.version() Returns version for each attached hardware.

🚗 Base control and Navigation

For drive, dock, and goto, the block parameter is set to True by default, meaning the function will block other processes until the action is complete. Set it to False if you want to allow other actions to run concurrently.

• Hackerbot.base.drive(linear_velocity, angular_velocity, block=True) This function moves the base with the provided velocity for around 3 seconds.

  • linear_velocity: (float) in mm/s – forward (+), backward (−)

  • angular_velocity: (float) in deg/s – left (+), right (−)

• Hackerbot.base.dock(block=True) This function makes robot drive back to charger.

• Hackerbot.base.maps.goto(x, y, angle, speed, block=True) Moves the robot to a position on the map.

  • x, y: (float) position in map coordinates

  • angle: (float) final orientation in degrees

  • speed: float (0.1 - 0.4)

• Hackerbot.base.maps.list() Returns the list of available maps.

• Hackerbot.base.maps.fetch(map_id) Fetches compressed data for a specific map.

• Hackerbot.base.speak(model_src, text, speaker_id) Utilize piper tts to handle text to speech.

  • model_src: (string) path to voice model.

  • text: (string) output texts.

  • speaker_id: (int) default to None, use it if the model support multiple speakers.

---

🤖 Head Control

• Hackerbot.head.look(pan, tilt, speed) Moves the head.

  • pan: (float) horizontal angle from 100.0 (right) to 260.0 (left)

  • tilt: (float) vertical angle from 150.0 (down) to 250.0 (up)

  • speed: (int) movement speed from 6 (slow) to 70 (fast)

• Hackerbot.head.eyes.gaze(x, y) Moves the animated eyes to gaze at a given screen coordinate.

  • x, y: (float) screen positions, range from -1.0 to 1.0

---

🦾 Arm & Gripper Control

• Hackerbot.arm.move_joints(j1, j2, j3, j4, j5, j6, speed) Moves all six arm joints.

• Hackerbot.arm.move_joint(joint, angle, speed) Moves a single joint.

  • joint: (int) joint index (1–6)

  • angle: (float) desired angle in degrees

  • speed: (int) movement speed from 0 (slow) to 100 (fast)

• Hackerbot.arm.gripper.open() Opens the gripper.

• Hackerbot.arm.gripper.close() Closes the gripper.

• Hackerbot.arm.gripper.calibrate() Calibrates the gripper for correct force and position.

---

🧹 Cleanup & Shutdown

Depends on functionality, clean up is necessary for the program to terminates due to current serial reading functionality.

Hackerbot.base.destroy(auto_dock=True)

• auto_dock: (bool) If True, the robot will dock before termination

⚠️ Required for clean termination due to ongoing serial communication.

---

🛠️ Troubleshooting

Error in setting up hackerbot helper

• Causes:

  • Flask API blocking serial port

  • Main controller unresponsive

• Fixes:

  • For Flask API:

    stop-flask-api
    # or manually
    ps aux | grep flask
    kill -9 <PID>

  • For main controller: Unplug and replug the power cable.