How to write a Pyrame module in Python

This document describes how to implement a new module in Python and how to use it with cmdmod.

A module is a piece of software used to drive a piece of hardware or an abstract entity. We typically use a module to manage multiple devices of the same flavour. It is composed of two files: a description file in XML and an implementation file in Python. The cmdmod tool is used to run it.

In the following, we create from scratch a new module named “test”.

Creating the description file

The description file contains all the information needed by the module for running:

  • the name of the module
  • the used language
  • the code file complete path

It should look like this :


Defining the TCP port of the module

The Pyrame module need to be adressed via a TCP socket described by its port. To manage properly all the ports and avoid conflicts, they are all stored in a file: /opt/pyrame/ports.txt file.

You just need to add the number of your new test module in that file this way


By convention, we use the capitalized name of the module followed with _PORT as a name. Verify that the port you use is free on your machine (that is, it does not collide with another Pyrame module nor with some other network service).

Implementation of the Python module

Now that we have a description file, we have to implement the functions in a Python file.

The cmdmod extension

As stated in the cmdmod documentation, cmdmod is basically a virtual machine with a TCP/XML/Pyrame protocol decoder. Thus, the core of a module is a set of functions that respond to requests.


Pyrame protocol does not accept to name the arguments of functions, so optional arguments must always be at the end of the list.

Hello world

This very basic function just returns 1 as return value (which means success) and “Hello World” as return text:

def helloworld_test():
  return 1,"Hello World"

Any time a return is encountered, the module exits from this function and send the result through the opened TCP socket. The result must have the form number,message. The number is an error code: 1 means “ok”, 0 means “error”. The message is the content of the result, it can be any string with no new line.

A more complicated example

Here is a little bit more complicated example showing parameters manipulation:

def helloworld_test(name):
  if name=="badname":
    return 0,"Helloworld function does not like badname"
  if name=="":
    return 1,"Hello World"
    return 1,"Hello %s"%(name)

Calling another module

To construct complicated systems, the modules have to rely on others. This is why a module can call another one with the execmd primitive.

Here is an example of a serial helloworld. It just opens a serial communication with a device having imprint “abcd:efgh” and sends Hello World on this serial link. Please see serial module documentation for details on the serial functions:

def serialhelloworld_test():

  #first we need to initialize the serial link
  #"usb_serial_converter" is an arbitrary name given to the link, we will use it as a handler in the sequel any time we need to use a serial function
  if retcode==0:
    return 0,"cant init serial: %s"%(res)

  #here we write "Hello World\n" on the link
  retcode,res=submod.execmd("write@serial","usb_serial_converter","Hello World\n")
  if retcode==0:
    return 0,"cant write to serial: %s"%(res)

  #communication is over, we now need to deinitialize the serial link
  if retcode==0:
        return 0,"cant deinit serial: %s"%(res)
        return 1,"Hello World successfully sent on serial"

You can see that in case of error, we pipeline the error reason to the next level

return 0,"error in something: %s"%(res)

This way, at any level we get the deepest error messages, allowing to debug easilly.

Testing the module

Now, our module is completed. We just have to install it and test it.

By convention, all the Pyrame modules are stored in the /opt/pyrame folder but you can place it wherever you want (accordingly with the path declared in the xml file).

Launching cmdmod

Launching cmdmod is very simple:

cmdmod /opt/pyrame/cmd_test.xml

It takes as its only parameter the description file with its path. The output of the module is the standard output. Optionally, you can add the “-d” flag to get debug messages.

You should see an output like:

test: 09:12:45 : module test language=python file=/opt/pyrame/ port=9212 up and running

Once you see this message, the module is ready to receive commands.

Sending commands with chkpyr

chkpyr2 is a tool that allows to send Pyrame commands through the command line. Its syntax is host port function [parameters]

As we want to check our test module with the second version of the helloworld function, we should type "localhost" "9212" "helloworld_test" "Fred"

Fred is the value for the name parameter. Double quotes are not necessary. Dont forget to escape your internal double quote with antislash. We get the result

retcode=1   res=Hello Fred

If you don’t want to use the numerical value of the port, type before:

. /opt/pyrame/

You can then replace 9212 by $TEST_PORT: localhost TEST_PORT helloworld_test Fred

You can pass a void argument localhost TEST_PORT helloworld_test ""

and then we have the “Hello World” result

retcode=1   res=Hello World

Finally if we use the “badname” value localhost TEST_PORT helloworld_test badname

We get an error

retcode=0   res=Helloworld function does not like badname

Other languages

Cmdmod has support for other languages than Python. You can use Lua, C, C++, shell or R to code your module. Please, have a look at the test programs to get syntax details: