# Python Package

***

## ⚡ Quick Start

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

<pre class="language-bash"><code class="lang-bash"><strong>pip install hackerbot
</strong></code></pre>

Or upgrade the existing package:

```sh
pip install --upgrade hackerbot
```

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

```python
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.

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

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

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

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

```python
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

{% hint style="info" %}
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.
{% endhint %}

* `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:

    ```bash
    stop-flask-api
    # or manually
    ps aux | grep flask
    kill -9 <PID>
    ```
  * For main controller: Unplug and replug the power cable.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hackerbot-industries.gitbook.io/documentation-hackerbot-industries/software/python-package.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.