How to Make a Hello World Matrix Application

How to Make a 'Hello World' Matrix Application

This article will discuss making an arbitrary Matrix application in a 'how to' tutorial like format, for details on the inner workings of Matrix, please see the Matrix User Guide.

Add a new button to Matrix

First we add a new button to the Matrix GUI somewhere, in this case lets put one under System Settings. Since Matrix uses html files to define the user interface, we need to edit the menu_settings.html file, which is found in /usr/share/matrix/html on the target filesystem, or the base folder of the matrix_gui sources.

Note that here we are assuming you have a NFS exported filesystem in your SDK install (replace the Xs with your version), if you have a NFS exported filesystem elsewhere you can adjust the command accordingly.

Note that depending on your filesystem's permissions you may need to use root to edit this file (as well as others in the NFS filesystem), if so you can start your editor with gksudo (i.e. gksudo gedit ~/...).

host $ gedit ~/ti-sdk-XXXX-evm-x.x.x.x/filesystem/usr/share/matrix/html/menu_settings.html

This defines what buttons the user sees in the settings menu, where the buttons are, what image they have, what label they have, and what they do, for details on the formatting please see this section of the Matrix Users Guide.

Since the existing buttons already have the basics laid out for us, we can just duplicate one of those, so copy the button contents from an existing button, to a new button lower down so that we add a new button to the second row, the existing button code should look something like the below.

          <object type="application/x-matrix" width="96px" height="96px">
         <param name="iconName" value="/usr/share/matrix/images/info-icon.png" />
         <param name="iconLabel" value=" Task Information" />
         <param name="appName" value="taskInfo" />
        </object>

If we copy this and paste it in a lower <td> segment (these define entries in a table in HTML, so we are making a table of buttons), we can make a duplicate button. At this point your button should have the same behavior of the original button if you were to run Matrix on a target and click into the menu, the html file should have something like the below in it (with the rest of the html above and below).

...
        <param name="appName" value="taskInfo" />
       </object>
     </td>
   </tr>
   <tr>
     <td align="center" width="96px" height="96px">
        <object type="application/x-matrix" width="96px" height="96px">
         <param name="iconName" value="/usr/share/matrix/images/info-icon.png" />
         <param name="iconLabel" value=" Task Information" />
         <param name="appName" value="taskInfo" />
       </object>
     </td>
     <td align="center" width="96px" height="96px">
     </td>
...

From here you can change the button image, the label, or the app itself.

Modifying the New Button

The HTML used to define the button in the table of buttons is fairly self explanatory (detailed further here), in general you probably want to keep the same sizes so the heights and widths can be left at 96.

To change the icon you simply need to point to an other icon on the target file system, either another from within the provided Matrix icons, or one of your own.

<param name="iconName" value="/usr/share/matrix/images/info-icon.png" />

The label underneath each icon is defined by the next value, and is also easily changed.

<param name="iconLabel" value=" Hello World!" />

The final value points to the particular application you want Matrix to run upon the user clicking on the icon, this is the name of the application's start up script which will be discussed in the next section.

<param name="appName" value="helloWorld" />

Preparing an App to Run from Matrix

Matrix does not execute applications directly, rather it relies on executing scripts that exist in /usr/bin of the target filesystem (the scripts used by matrix are in the /bin directory of the matrix_gui sources). This being said, the appName value mentioned in the prior section must match the script name in /usr/bin of your target filesystem. For a simple hello world example, make a text file in /usr/bin of the target called helloWorld.

Note that depending on your filesystem's permissions you may need to use root to edit this file (as well as others in the NFS filesystem), if so you can start your editor with gksudo (i.e. gksudo gedit ~/...).

host $ gedit ~/ti-sdk-XXXX-evm-x.x.x.x/filesystem/usr/bin/helloWorld

Now add the below to the helloWorld file using your favorite editor.

echo "Hello World!"

Now to ensure we can execute this script we will need to give it execute permissions, which can be done on the target.

target $ cd /usr/bin
target $ chmod +x helloWorld

After this, if you start up Matrix on the target and navigate through the GUI to the button you created, you should see the Hello World! output when you press the button.

target $ /etc/init.d/matrix-gui start

Congratulations, you now have a very simple Matrix application, and can run other basic command line commands from the Matrix GUI by modifying the helloWorld script, or creating a new script.