ubuntu-based-kiosk/TALKKONNECT_SETUP.md

TalkKonnect Mumble Client Setup Guide

This guide will help you set up TalkKonnect as a headless Mumble client on your kiosk.

The Permission Issue (FIXED)

The original installation script had a bug where it created the configuration directory in the script runner's home directory instead of the target user's home directory. This caused a "permission denied" error when the service tried to run.

The fix has been applied to talkkonnect_complete_install.sh

Quick Fix for Existing Installations

If you already ran the installation and got the permission error, run this:

sudo ./fix_talkkonnect_permissions.sh

This will:

• Move the config to the correct user's home directory
• Fix all file permissions and ownership
• Verify your systemd service configuration

Fresh Installation

For a new installation, simply run:

./talkkonnect_complete_install.sh

When prompted, enter the username that should run talkkonnect (e.g., user or kiosk).

The script will now:

1. Install all dependencies
2. Build talkkonnect with the correct Opus library fixes
3. Create the config in the TARGET user's home directory (FIXED)
4. Set proper ownership and permissions (FIXED)
5. Set up the systemd service to run as the target user

Configuration

After installation, edit the configuration file:

# If you're the target user:
nano ~/.config/talkkonnect/talkkonnect.xml

# If talkkonnect runs as a different user (e.g., 'user'):
sudo nano /home/user/.config/talkkonnect/talkkonnect.xml

Required Settings

Update these fields in the XML:

<serverandport>your.mumble.server:64738</serverandport>
<username>your_username</username>
<password>your_password</password>
<channel>Root</channel>

Self-Signed Certificates

If your Mumble server uses a self-signed certificate, set:

<insecure>true</insecure>

Voice Activation vs PTT

Voice Activation (Default):

<voiceactivity enabled="true">
  <settings threshold="0.3" holdtimems="1000" holdtimeoutms="2000"/>
</voiceactivity>
<ptt enabled="false"/>

Push-to-Talk with USB Keyboard:

<voiceactivity enabled="false"/>
<ptt enabled="true">
  <usbkeyboard enabled="true" device="/dev/input/event0" keycode="KEY_F13"/>
</ptt>

To find your USB keyboard device:

sudo evtest

Testing

Manual Test

Before enabling the service, test manually:

# If running as yourself:
/usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml

# If running as a different user (e.g., 'user'):
sudo -u user /usr/local/bin/talkkonnect -config /home/user/.config/talkkonnect/talkkonnect.xml

You should see:

• Connection to Mumble server
• Join the specified channel
• No permission errors

Common Errors

"permission denied" on config file:

• Run ./fix_talkkonnect_permissions.sh
• OR manually: sudo chown -R user:user /home/user/.config/talkkonnect

"unable to unmute" errors:

• This is usually non-fatal; audio may still work
• Check: amixer scontrols

Connection refused:

• Check your <serverandport> setting
• Verify firewall allows outbound connections on port 64738

Certificate errors:

• Set <insecure>true</insecure> for self-signed certs

Systemd Service (if available)

If your system uses systemd:

# Enable and start
sudo systemctl enable talkkonnect
sudo systemctl start talkkonnect

# Check status
sudo systemctl status talkkonnect

# View logs
journalctl -u talkkonnect -f

Docker/Non-Systemd Environments

If you're running in Docker or without systemd, run talkkonnect directly:

# Create a simple start script
cat > ~/start-talkkonnect.sh << 'EOF'
#!/bin/bash
/usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml
EOF

chmod +x ~/start-talkkonnect.sh

# Run it
./start-talkkonnect.sh

Or run in the background:

nohup /usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml > ~/talkkonnect.log 2>&1 &

Audio Configuration

ALSA (Direct)

Best for single-application use:

<input>
  <settings enabled="true" device="hw:0,0" samplerate="48000" channels="1"/>
</input>
<output>
  <settings enabled="true" device="hw:0,0" samplerate="48000" channels="1"/>
</output>

PulseAudio/PipeWire

Best for multi-application use:

<input>
  <settings enabled="true" device="default" samplerate="48000" channels="1"/>
</input>
<output>
  <settings enabled="true" device="default" samplerate="48000" channels="1"/>
</output>

List available devices:

aplay -L        # List output devices
arecord -L      # List input devices

Programmatic Channel Switching

TalkKonnect can join a specific channel on connect by setting:

<channel>Your/Channel/Path</channel>

Use / to separate nested channels:

• Root - joins root channel
• General - joins General channel
• General/Support - joins Support subchannel under General

To switch channels at runtime, TalkKonnect has an API you can enable:

<api enabled="true">
  <listenport>8011</listenport>
</api>

Then use HTTP requests to control it:

# Switch channel
curl http://localhost:8011/api/channel?channel=General/Support

Troubleshooting

Common Warnings (Usually Non-Fatal)

These warnings often appear but don't prevent talkkonnect from working:

Unable to Unmute failed to execute "pactl set-sink-mute 0 0"

• TalkKonnect is trying to unmute your audio output
• This usually fails because the sink index is wrong or pactl isn't accessible
• Audio typically works anyway - this is just a cosmetic error
• To fix: Run ./fix_talkkonnect_audio.sh to check your audio configuration

Unable to Find Channel Name: Root

• Just a warning - connection usually succeeds anyway
• The channel exists but talkkonnect didn't detect it during initial scan
• You'll see a follow-up message showing successful connection

Failed to connect PipeWire event context (errno: 112)

• TalkKonnect is trying to use PipeWire but can't access the session
• Usually happens when running as a service without proper environment
• If you see Speaking -> messages, audio is working!
• To fix: Ensure XDG_RUNTIME_DIR is set correctly in systemd service

Audio Troubleshooting

Run the audio diagnostic script:

./fix_talkkonnect_audio.sh

This will:

• Check PipeWire/PulseAudio session status
• List available audio devices
• Show current talkkonnect configuration
• Provide specific recommendations

Quick audio test:

# Test as the kiosk user (replace with your user)
sudo -u kiosk XDG_RUNTIME_DIR=/run/user/$(id -u kiosk) speaker-test -t wav -c 2 -l 1

View Logs

# Config file log
cat ~/.config/talkkonnect/talkkonnect.log

# Systemd logs (if applicable)
journalctl -u talkkonnect -f

# Manual run (shows errors directly)
/usr/local/bin/talkkonnect -config ~/.config/talkkonnect/talkkonnect.xml

Common Issues

1. No audio input/output:

   • Check aplay -l and arecord -l
   • Verify user is in audio group: groups
   • Test audio: speaker-test or arecord -d 5 test.wav && aplay test.wav

2. Can't access /dev/input devices (for PTT):

   • Verify user is in input group: groups
   • May need to log out and back in after adding to group

3. Connection drops frequently:

   • Check network stability
   • Increase keepalive timeouts in config
   • Check server logs

4. Permissions errors:

   • Run ./fix_talkkonnect_permissions.sh
   • Verify config directory ownership: ls -la ~/.config/talkkonnect

Files and Locations

• Binary: /usr/local/bin/talkkonnect
• Config: ~/.config/talkkonnect/talkkonnect.xml
• Logs: ~/.config/talkkonnect/talkkonnect.log
• Service: /etc/systemd/system/talkkonnect.service (if using systemd)
• Source: ~/talkkonnect

Security Notes

• Config file contains your Mumble password in plain text
• Protect it: chmod 600 ~/.config/talkkonnect/talkkonnect.xml
• Consider using certificate-based authentication instead of passwords
• For production, use proper systemd hardening options

Next Steps

1. ✅ Fix permissions (if needed): ./fix_talkkonnect_permissions.sh
2. ✅ Edit config: nano ~/.config/talkkonnect/talkkonnect.xml
3. ✅ Test manually first
4. ✅ Enable systemd service (if applicable)
5. ✅ Configure audio ducking for multi-app environments (optional)
6. ✅ Set up API for programmatic control (optional)

References

• TalkKonnect GitHub
• Mumble Protocol
• Config file path: ~/.config/talkkonnect/talkkonnect.xml