58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# Jibo Hub-Shim Server: Deployment & Usage Guide
|
|
|
|
## Quick Start
|
|
1. **Install dependencies** (if needed):
|
|
- Node.js v16+ (recommended v18+)
|
|
- `npm install` (if package.json present)
|
|
2. **Configure**:
|
|
- Edit `config.json` (or use `config.example.json`):
|
|
- `listen.port`: Port to listen on (default: 9000)
|
|
- `listen.path`: WebSocket path (default: `/v1/listen`)
|
|
- `asr.baseUrl`: Local ASR HTTP endpoint
|
|
- `logging.level`: `info`, `debug`, etc.
|
|
3. **Run the server**:
|
|
```sh
|
|
node index.js config.json
|
|
```
|
|
- Or set `JIBO_HUB_SHIM_CONFIG` env var.
|
|
|
|
## Integration with Jibo Robot
|
|
- The robot's `jibo-jetstream-service` binary must be configured to connect to the hub-shim:
|
|
- `hub_port`: 9000 (or your chosen port)
|
|
- `hub_hostname`: IP of the machine running hub-shim
|
|
- `listen_url`: `/v1/listen`
|
|
- Confirm with logs: hub-shim should show `ws connected` and `listen result` for each turn.
|
|
|
|
## How It Works
|
|
- The robot opens a WebSocket to hub-shim for every listen turn.
|
|
- hub-shim receives CONTEXT and LISTEN messages, runs ASR/NLU, and sends a TURN_RESULT.
|
|
- The TURN_RESULT is always local (`global: false`), with `status: 'SUCCEEDED'` and the correct intent/entities.
|
|
- This resolves the skill's local turn and allows menu/intro flows to advance by voice.
|
|
|
|
## Troubleshooting
|
|
- **No skill advancement?**
|
|
- Check that TURN_RESULT is sent with `status: 'SUCCEEDED'`, `global: false`, and correct `requestID` (should match transID).
|
|
- Use robot-logger (`/tmp/jibo-skills.log` or web panel) to trace intent and state.
|
|
- **ASR timeouts?**
|
|
- Ensure ASR service is running and reachable from hub-shim.
|
|
- **NLU not matching?**
|
|
- Edit `inferNluFromText()` in `index.js` to adjust rule patterns.
|
|
|
|
## Advanced
|
|
- **Custom NLU**: You can extend `inferNluFromText()` for more complex intent/entity extraction.
|
|
- **Client-supplied ASR/NLU**: Send CLIENT_ASR or CLIENT_NLU messages before LISTEN to inject results.
|
|
- **Logging**: Adjust `logging.level` in config for more/less verbosity.
|
|
|
|
## File Locations
|
|
- Main server: `index.js`
|
|
- Config: `config.json` or `config.example.json`
|
|
- Protocol doc: `HUB-SHIM_PROTOCOL.md`
|
|
|
|
## Support
|
|
- For protocol or integration issues, see HUB-SHIM_PROTOCOL.md and the source code comments.
|
|
- For robot-side debugging, use robot-logger and check `/tmp/jibo-skills.log`.
|
|
|
|
---
|
|
|
|
# Enjoy fully offline Jibo skills and menus!
|