Project files

07 — API Key Acquisition and Configuration Guide

⭐ Before using this tutorial, please support this open-source project:

1. Star ⭐ — Click the ⭐ Star in the top-right corner of the GitHub repository to bookmark this project for easy future access
2. Fork 🍴 — Click Fork to copy the project to your GitHub account, allowing you to modify it freely
3. Download 📥 — Click the green Code button → Download ZIP to download it locally and start replicating

📸 Operation Diagram:

MindPaw uses two cloud-based APIs and an offline voice module, all of which require application or configuration before use. This guide will walk you through all the necessary configurations step by step.

Table of Contents

• 1. Xinzhi Weather API (Weather Query)
• 2. Volcano Engine Ark API (AI Conversation)
• 3. HLK-V20 Voice Module Configuration
• 4. Configuration on the Robotic Dog

1. Sensors.AI Weather API (Weather Query)

1.1 Register an Account

1. Open the Seniverse Weather official website (opens in a new tab)
2. Click Sign Up in the top-right corner
3. Register using an email address or GitHub account
4. Log in after registration

1.2 Obtaining an API Key

1. After logging in, go to the console and click Product Management on the left side.
2. Find Weather Data API and click Free Version.
3. The free version allows up to 1,000 calls per day, which is more than enough for personal robots.
4. After successful creation, you will see a key similar to the following on the page:

Your API Key: S_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5. Click Copy and save it to a notepad for future use.

1.3 Location in the Code

The obtained API Key does not need to be hardcoded in the code; it can be configured via the web page (see Section 4).

// main.cpp line 65 — API Key defaults to empty, filled in via the web page
String weatherapi = ""; // Filled in via the web page after startup

2. Volcano Engine Ark API (AI Conversation)

MindPaw calls the Doubao Large Model through the Ark platform of Volcano Engine, and the interface is fully compatible with the OpenAI format.

2.1 Register an Account

1. Visit the Volcano Engine official website (opens in a new tab)
2. Click Sign Up in the top-right corner (supports phone number / email)
3. Complete real-name authentication after registration (required for AI services)
4. Log in to the console

2.2 Creating an Inference Access Point

1. Enter 方舟 in the search box at the top of the console to access the 方舟平台.
2. Select Inference Access Points from the left-hand menu.
3. Click Create Access Point and fill in the following:

4. After creation, you will receive an Endpoint ID, formatted as:

ep-2025xxxx-xxxxx-xxxxx-xxxx

5. Copy this ID and save it for future use

2.3 Obtaining an API Key

1. In the left menu of the Ark platform, click API Key Management.
2. Click Create API Key.
3. After entering a name, you will receive:

AK:  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

4. Click Show Full Key and copy it (the full content will not be displayed again after closing the page).
5. Save the API Key and Endpoint ID to a notepad.

2.4 (Optional) Recharge

New users typically have tens of thousands of free Token quotas, which are sufficient for a long time. If you need to recharge later:

1. Ark Platform → Billing Center
2. Recharge ¥10 can last a very long time (Doubao-pro is about ¥0.8 per million tokens)

2.5 Location in the Code

// doubao_config.h Line 10 — API endpoint (pre-filled, no need to modify)
#define DOUBAO_BASE_URL   "https://ark.cn-beijing.volces.com"
#define DOUBAO_API_PATH   "/api/v3/chat/completions"

The API Key and Endpoint ID are configured via the web interface and are not hardcoded in the code.

3. HLK-V20 Voice Module Configuration

HLK-V20 (also known as SU-03T) is an offline voice recognition module that can recognize voice commands without an internet connection.

3.1 Downloading the Configuration Tool

1. Search for "SU-03T Configuration Tool" or "HLK-V20 Host Computer" on Baidu.
2. Alternatively, you can find the download link on the official Taobao store page of Hi-Link.
3. The tool is a Windows software, approximately 200MB in size.

3.2 Connecting the Module to a Computer

Use a USB-TTL module for connection:

Note:

• Do not connect 5V; the HLK-V20 is powered by 3.3V
• RX/TX must be cross-connected (TX→RX, RX→TX)

3.3 Configuring Voice Commands

Open the configuration tool and follow these steps:

Step 1: Set Basic Parameters

Step 2: Add Commands

Click Add Command. Each command consists of:

• Recognition Word: What the user says (e.g., "前进")
• Output: The string sent via serial port after recognition (e.g., CMD1)

Create 22 commands based on the following table:

Step 3: Flash to Module

1. Click Flash or Generate Firmware and Download
2. Wait for flashing to complete (approximately 10-30 seconds)
3. Disconnect the USB-TTL after flashing is done

3.4 Verification

After flashing, connect the module using a USB-TTL adapter:

1. Open a serial terminal (baud rate 9600)
2. Speak to the module; the serial output should display corresponding strings such as CMD1, CMD2, etc.
3. If there is no response, check whether the microphone is functioning properly and whether the recognition words are spoken clearly

4. Configuring on the Robotic Dog

4.1 Connecting to WiFi

1. Power on the robotic dog.
2. Use your phone/computer to search for the WiFi hotspot MindPaw.
3. Enter the password mindpaw1234.
4. After successful connection, open http://192.168.4.1 in your browser.

4.2 Configuring the Weather API

1. On the console page, click Online Features → Settings.
2. Locate the Weather API Key input box.
3. Paste the API Key copied from 心知天气 (XinZhi Weather).
4. Enter the city name (e.g., Shanghai, Beijing).
5. Click Save and Connect.
6. Return to the Online Features page and click Weather to verify normal display.

4.3 Configuring the AI Agent

1. Open http://192.168.4.1/aiconfig.html in your browser.
2. Paste the Volcano Engine API Key into the API Key input field.
3. Paste the Endpoint ID into the Inference Endpoint ID input field.
4. Click Save Configuration.
5. After the success prompt appears, open http://192.168.4.1/aichat.html.
6. Enter a message for testing; the robotic dog should respond with actions, expressions, and melodies.

4.4 Verifying HLK-V20

After connecting the HLK-V20 module, no additional configuration is required—it is ready to use once powered on:

1. Say the wake-up word to the module (e.g., "Xiaogou Xiaogou").
2. After hearing the module's prompt tone, speak the command (e.g., "Move forward").
3. Observe whether the robotic dog performs the corresponding action.
4. If there is no response, check the wiring (see 05_Assembly_Guide.md).

Frequently Asked Questions

Weather API shows "Need NET"

• Is the robotic dog connected to WiFi? (The OLED displays AP mode, requiring an external WiFi connection)
• Re-enter and save the WiFi information on the Settings page

AI Chat Prompt "AI Not Configured"

• Check if aiconfig.html was saved successfully
• Check if the API Key and Endpoint ID were copied completely (no extra spaces)
• Has the Volcano Engine account completed real-name authentication?

HLK-V20 No Response

• Is the wiring correct? Are RX/TX crossed?
• Is the baud rate set to 9600?
• Has the firmware in the module been successfully flashed? (Test the output separately using a USB-TTL adapter)
• When speaking to the module, do not stand too far away (recommended distance: 0.5–1 meter)

Inconsistency between voice commands and actual execution

• Is the correspondence between the recognition words and output strings of the HLK-V20 correct?
• Check whether the DEFAULT_MAPPING table in hlkv20.cpp matches your output strings

What should I do if the secret key is leaked?

• 心知天气 (Sensoro Weather): Log in to the console → Product Management → Reset Key
• 火山引擎 (Volcano Engine): Log in to the Ark platform → API Key Management → Delete old Key → Create new Key
• WiFi Password: Modify the password in main.cpp and recompile and reflash