API Application Programming Interface

From VoxCommando
Jump to: navigation, search

You can send commands to VoxCommando by many different methods: UDP, TCP, HTTP, or command line. To use TCP or HTTP you need to enable and configure the TCP plugin.

Message format

Regardless of how messages are sent to VoxCommando, the message itself will always be a single string using the following format:
Action Type&&Parameter1&&Parameter2&&Parameter3 etc.

Here are some sample messages:

Perform Basic Actions

TTS.Speak&&Hi there!

Emulate a voice command using the VC.TellVox action

Note: Spelling must match your tree phrases & payloads exactly!

VC.TellVox&&Play artist Buck Jones

Triggering Events

VC.TriggerEvent&&MyEvent.Name&&I am Payload 1&&and I am Payload 2

UDP

By default VoxCommando listens for UDP messages on port 33000, but you can change this in options.

You can send messages to VoxCommando using any program or device that can send UDP messages such as EventGhost, Vera, iRule, VoxWav, and many other remote programs and apps etc.

You can send UDP messages from the command line using VoxCommando.exe or udpsender.exe.

To send messages from Vera home controllers, you can use the Luup programming script in your Vera triggers and automation scenes. Please see this forum post as well as this one for more information.

Other home controllers that allow Lua scripting may work similarly if they can send UDP messages.

You can send UDP messages to VoxCommando from iRule, Tasker, etc. Please consult the documentation for the device or application you are using to learn how to send UDP messages.

You can send UDP messages to VoxCommando from EventGhost using the Broadcaster plugin.

You can also send UDP messages using TellVoxCommando.exe which facilitates the formatting of the messages for basic commands. TellVox can sometimes be handy for testing, but usually we just test commands from within the command editor, which is more powerful.

Command Line

Command line tools essentially allow you to send a message to VoxCommando using UDP. You can either use VoxCommando.exe or the small utility udpsender.exe which is part of the "extra tools" available on the Download Page

TCP

You can create a TCP server with the TCP plugin.

HTTP

TCP settings.png
You can create a simple HTTP web server with the TCP plugin.

In the TCP plugin settings, you can enable a web server, choosing the port. If enabled in settings, the web server will run whenever VoxCommando is running.

It is also possible to start and stop a web server using TCP actions within your commands.

HTTP requests to VoxCommando take the form:

http://[your IP address]:port/api/{see message syntax above}

Note that in the example shown in the plugin settings, the IP address 127.0.0.1 refers to the standard loopback IP for local host. If you're sending requests from a different computer on your network, you'll need to know the true IP address for the machine running VoxCommando.