Hoppa till huvudinnehåll

Setup and configuration

Prepare the globe computer​

You need the built TellUs AI package, a separate asset library, Node.js 20 or later on the globe computer, a microphone and speakers, and internet access for the assistant. Ethernet, Wi-Fi, or 5G can provide that internet connection; 5G is not a software requirement.

Connect the microphone receiver and speakers before starting the app. The project has used a RØDE Wireless PRO microphone, but select the devices actually present at your site.

  1. Extract the complete app package into your PufferConsole applications directory, for example C:\PufferConsole\applications\TellUsAI.
  2. Extract tellus-data to a suitable folder. It can live separately from the application.
  3. Copy the supplied config.example.json to config.json beside run.exe.
  4. Set openaiApiKey and assetsPath. Keep the real key in the local configuration.
  5. Start TellUs AI from PufferConsole, or run the package's run.exe on the globe computer.

Keep the packaged directory structure intact; the launcher expects its components under infra.

Configuration reference​

Start with the supplied example. For a standalone globe, keep mode: "server" and assets: "local". Restart after configuration edits.

All launcher settings (reference)
FieldExample / starting valuePurpose
mode"server"Starts the local service server. "remote" connects the service client to remoteUrl.
port8000Local WebSocket server port in server mode.
remoteUrl"wss://example.com/tellus-server/"Service connection in remote mode. Replace the placeholder for a remote installation.
services["tuio", "audio", "openai", "scenario", "thumbnails"]Starts touch, hardware audio, AI, orchestration, and shared quick-topic configuration. Keep thumbnails enabled for editable quick topics.
assets"local"Serves the local asset folder. "remote" uses remoteAssetsUrl. Independent of server/remote service mode.
assetsPath"C:\\PufferConsole\\applications\\tellus-data"Absolute local data directory containing index.json.
assetsPort3002Local asset HTTP port.
remoteAssetsUrl"https://example.com/tellus-data"Root of the remote asset library in remote asset mode.
frontendPort3000Operator dashboard HTTP port.
webrenderPort3001Browser renderer and second-screen preview HTTP port.
tuioUrl"ws://localhost:8080"Touch input connection on the globe computer.
consoleMode"hidden"No child console windows; service output is written under logs. "shared" also shows combined output. "separate" opens individual consoles and does not provide those launcher log files.
defaultMicMutedfalse in the current exampleControls launch-time microphone mute. Set true to start quietly. If omitted, the launcher defaults to true.
openaiApiKeyEmpty in the exampleYour site's OpenAI API key. Must be set for AI conversation.

mode selects the service connection; assets selects the data source. Remote setups need an installation-specific plan.

JSON strings need escaped Windows backslashes. For the example data location, write:

{
"assets": "local",
"assetsPath": "C:\\PufferConsole\\applications\\tellus-data",
"defaultMicMuted": true
}

This excerpt belongs in the full configuration. Use valid JSON without comments or trailing commas.

Model, voice, personality, and rules are adjusted in the frontend; they are not extra fields in this launcher example. See scenario profiles.

Connect from a tablet or laptop​

Use the same reachable network as the globe computer. If its hostname is pufferfish, open:

  • Main interface: http://pufferfish:3000/
  • Quick topics: http://pufferfish:3000/topics
  • Service dashboard: http://pufferfish:3000/dashboard/services
  • Second-screen preview: http://pufferfish:3001/?display=screen

Replace pufferfish with your installation's hostname or IP address. On a tablet, localhost means the tablet itself. Use your configured ports if they differ from the examples.

The preview receives scene updates but keeps dragging local. Use Webrender to control the real globe.

Verify startup​

Open the home page and check connected. Under Scenario Configuration, the normal local service selections are:

SelectionTypical value
Scenario servicescenario:node:1
Scenarioguide
Scenescene:webrender:1
Assistantassistant:openai:1
Touchtouch:tuio:1
Audioaudio:hardware:1

Service instance numbers can differ. An empty separate Transcriber selection is not itself a problem for guide mode, which uses the realtime assistant's input transcription.

Check the selected microphone and speaker in the audio tab. Then try loading Blue Marble using the Webrender tab. The initial startup map is a placeholder, so select a catalogue asset before testing dataset features.

Do not rely solely on a spoken startup message; audio routing can hide it.

Preserve local content when updating​

Before replacing a package, stop the app and back up its local profiles and thumbnail files. Keep the real API configuration private and set the new installation's own key and asset path. Reopen the UI and check the default profile, linked asset IDs, and audio devices after the update.