Home   Documentation   Demonstrations   Download

AMICO: Documentation / Basic Communication Protocols

 

  • AMICO currently supports wide range of communication interfaces, such as XML-RPC, OpenSound Control (OSC), URL, and SOAP, realized through different AMICO modules. All of these modules are realized on top of basic build-in AMICO TCP and UDP communication protocols. You can also directly communicate with AMICO using TCP connection, or by sending UDP packages formatted according to AMICO protocol, described in this document. TCP and UDP ports of the communicator are defined in the configuration file of AMICO module.

 

Basic TCP Communication Protocols

Following table gives a list of all available commands.

 

TCP Command (all command have to end with end of line characters "\r\n") Example Description
UPDATE <variable-name> <value> [<group>] [<description>] UPDATE age 26

UPDATE name James%30Bond

 Updates the variable. If the variable does not exist, it will be added. Group and description are optional. Name cannot contain empty spaces, while value, group and description have to UTF-8 encoded.
UPDATE-DIRECT <variable-name> <value> [<group>] [<description>] UPDATE-DIRECT age 26

UPDATE-DIRECT name James%30Bond

 The same as the UPDATE command, except that it do not trigger variable derivation transformations. Useful efficient, very frequent updates of variables.
DELETE <variable-name> DELETE age

DELETE name

 Deletes the variable. If the variable does not exists, nothing happens.
REGISTER [DIFF] <trigger-variables> <template> REGISTER age User is <%=age%> years old.

REGISTER age,name User <%=name%> is <%=age%> years old.

REGISTER DIFF message  New message: <%=age%>

 Adds a template that will be populated and returned to the application (through TCP connection) when some of the trigger variables changes. Values inside <%=variable-name%> will be replaced with the value of the variable. For example template "User age = <%=age%>",  with variable age updated to 27, will be populated to "User age 27". If the variable with a name does not exists, it will be replaced with empty string. If option DIFF is used, than the template is evaluated and send only when the value of the variable is different from previous value, not every time when variable is updated. List of trigger variables cannot have contain empty spaces. Populated templates are sent UTF-8 encoded.
POPULATE TEMPLATE <template> POPULATE TEMPLATE Value of variable age is <%=age%> On request population of templates.
GET <list-of-variables> GET age

GET age,name

 Returns comma separated, UTF-8 encoded list of values for given variable names.
GETXML <list-of-variables> GETXML age

GETXML age,name

 Returns comma separated, XML encoded list of values for given variable names. For example "<varaibles><variable name='age'>26</variable></variables>"
GETALLXML GETALLXML Returns comma separated, XML encoded list of values for all variables.
LOAD TRANSFORMATION <xslt-transformation-url> LOAD TRANSFORMATION http://amico.sf.net/sample.xsl Loads XSLT transformation for derivation of new variables.
REMOVE TRANSFORMATION <xslt-transformation-url> REMOVE TRANSFORMATION http://amico.sf.net/sample.xsl Removes XSLT transformation for derivation of new variables.
ONUNLOAD <command> ONUNLOAD DELETE age Specify command that will be executed when the communicator looses connection with some module. Command can be any of the previously enlisted TCP commands (UPDATE, DELETE, GET....)

 

Basic UDP Communication Protocols

UDP Interface currently supports just two command:
 

UDP Command Example Description
UPDATE <variable-name> <value> [<group>] [<description>] UPDATE age 26

UPDATE name James%30Bond

 Updates the variable. If the variable does not exist, it will be added. Group and description are optional. Name cannot contain empty spaces, while value, group and description have to UTF-8 encoded.
UPDATE-DIRECT <variable-name> <value> [<group>] [<description>] UPDATE-DIRECT age 26

UPDATE-DIRECT name Bond,James%30Bond

 The same as the UPDATE command, except that it do not trigger variable derivation transformations. Useful efficient, very frequent updates of variables.
DELETE <variable-name> DELETE age

DELETE name

 Deletes the variable. If the variable does not exists, nothing happens.
REGISTER [DIFF] <host> <udp-port> <trigger-variables> <template> REGISTER localhost 3391 age User is <%=age%> years old.

REGISTER localhost 3391 age,name User <%=name%> is <%=age%> years old.

REGISTER localhost 3391 message  New message: <%=age%>

 

 Adds a template that will be populated and returned to the application (through UDP package sent on specified host and UDP port) when some of the trigger variables changes. Values inside <%=variable-name%> will be replaced with the value of the variable. For example template "User age = <%=age%>",  with variable age updated to 27, will be populated to "User age 27". If the variable with a name does not exists, it will be replaced with empty string. If option DIFF is used, than the template is evaluated and send only when the value of the variable is different from previous value, not every time when variable is updated. List of trigger variables cannot have contain empty spaces. Populated templates are sent UTF-8 encoded.

 

 

Validation Logos