IPad ArtNet Node

Written by Tobi Schäfer, September 2010.

Prerequisites: libartnet 1.1.0, Mac OS X 10.6.4, Xcode 3.2.3, iPad w/ iOS 3.2

Using libartnet in the Xcode Simulator

This is documentation of my first steps using Art-Net, libartnet and Xcode. I am still a complete newbie with all these things. However, I suceeded in running a simple program on the iPad sending and receiving Art-Net data – not without help from the excellent people of the open-ligthing ML<ref>http://groups.google.com/group/open-lighting/browse_thread/thread/e3f322613b710d9d/661d7e4babba4bf1</ref>. I tried to sum up here my experiences so far, although I am sure there are better ways to achieve the same result.

Installing libartnet

curl -O http://code.google.com/p/linux-lighting/downloads/detail?name=libartnet-1.1.0.tar.gz
tar xzf libartnet-1.1.0.tar.gz
cd libartnet-1.1.0
./configure CC="gcc -arch i386"
make
sudo make install

Adding libartnet.dylib to XCode

Simply drag&drop the file libartnet.1.dylib from the /usr/local/lib directory to the Frameworks group in Xcode.

Hint: you can easily open hidden directories in a new window from within Terminal.app:

open /usr/local/lib

Add the path /usr/local/include to the Header Search Paths in the Search Paths section of your project or target and tick the recursive checkbox.<ref>http://iphone.olipion.com/cross-compilation/include-library-in-xcode-project</ref>

Using libartnet On The iPad

Getting libartnet to work on the iPad is a little bit trickier and involves cross-compiling the library for the iPad’s processor architecture.

Fortunately, there is help on the Intertubes.

Cross-compiling libartnet For The iPad

First of all, it is safer to remove already installed libartnet files if you should have built the dynamic library in a previous step. Otherwise you could follow the steps in Apple’s Technical QA1393 document.

rm -rf /usr/local/lib/libartnet.*

Then clean your libartnet build directory:

make distclean

I found a helper script which sets all necessary cross-compiling flag

Copy it to your Mac as build.sh. You probably need to modify the SDK version to your needs:

export SDKVER="3.2"

Furthermore, you should add the following line before the ./configure ... command to prevent another error from happening:<ref>http://groups.google.com/group/open-lighting/msg/28e002886ba95ced</ref>

export ac_cv_func_malloc_0_nonnull=yes

Make the file executable and then run the script:

chmod a+x build.sh
./build.sh

If it compiles it should install the file libartnet.a into the directory /opt/iphone-3.2/lib as well as the header files into </code>/opt/iphone/include</code>.

Adding libartnet.a To Xcode

As with libartnet.dylib drag&drop the libartnet.a file to the Frameworks group in Xcode.

Similarly, add the path /usr/iphone-3.2/include to the Header Search Paths in the Search Paths section of your project or target and tick the recursive checkbox.

Example Code

You now should be ready to build and run the following code in the Simulator as well as on the iPad. Thus, do not forget to select the corresponding setting from the Overview drop-down menu.

The code is just a proof of concept and not ready for production. It creates and sets up an Art-Net node, defines a handler method for incoming data and then creates an infinite loop sending Art-Net polls and checking for Art-Net input.

#import "artnet.h"
#import "packets.h"

int artnetReceiver(artnet_node node, void *pp, void *d) {
       NSLog(@"Receiving Art-Net data!");
       artnet_packet pack = (artnet_packet) pp;
       printf("Received packet sequence %d\n", pack->data.admx.sequence);
       printf("Received packet type %d\n", pack->type);
       printf("Received packet data %s\n", pack->data.admx.data);
       return 0;
 }

int main(int argc, char *argv[]) {
       
       char *ip_addr = NULL;
       
       uint8_t subnet_addr = 0; 
       uint8_t port_addr = 1;
       
       artnet_node *artnetNode = artnet_new(ip_addr, 1);
       
       if (!artnetNode) {
               printf("Error: %s\n", artnet_strerror());
               exit(-1);
       }
       
       artnet_set_long_name(artnetNode, "Art-Net Test");
       artnet_set_short_name(artnetNode, "ANT");
       
       // set the upper 4 bits of the universe address 
       artnet_set_subnet_addr(artnetNode, subnet_addr) ;
       
       // enable port 0        
       artnet_set_port_type(artnetNode, 0, ARTNET_ENABLE_OUTPUT, ARTNET_PORT_DMX) ; 

       // bind port 0 to universe 1 
       artnet_set_port_addr(artnetNode, 0, ARTNET_OUTPUT_PORT, port_addr); 
       
       artnet_dump_config(artnetNode);

       artnet_set_handler(artnetNode, ARTNET_RECV_HANDLER, artnetReceiver, NULL); 

       if (artnet_set_dmx_handler(artnetNode, dmxHandler, NULL) != 0) {
               printf("Error: %s\n", artnet_strerror());
               exit(-1);
       }       
       
       if (artnet_start(artnetNode) != 0) {
               printf("Error: %s\n", artnet_strerror());
               exit(-1);
       }       
       
       while (YES) {
               artnet_send_poll(artnetNode, NULL, ARTNET_TTM_DEFAULT);
               //printf("arnet_get_sd() => %i\n", artnet_get_sd(artnetNode));
               printf("artnet_read() => %i\n", artnet_read(artnetNode, 1));
       }
   
       // Use this to deallocate memory
       //artnet_stop(artnetNode);
       //artnet_destroy(artnetNode);
   
   return retVal;
}

Testing Data Transmission

If your program builds and runs without errors you now can test whether Art-Net data is sent and received. Wireshark<ref>http://www.wireshark.org</ref> is a handy tool for monitoring your network.

However, for sending Art-Net data you will need a more appropriate tool. I am using the OLA Command Line Tools, running them from another machine with GNU/Linux (Ubuntu 10.04) as operating system.

Although I did not test it, you probably can also install OLA on another Mac or even the same machine you are running XCode on, using the available Installer Disk Image and/or following the steps of the OLA On Mac OS X page.

Installing OLA On Ubuntu

Please refer to the OLA On Linux page.

If you should get the following error try to fix it with one of two available solutions:

Rpc.pb.cc: In copy constructor 'ola::rpc::RpcMessage::RpcMessage(const ola::rpc::RpcMessage&)': 
Rpc.pb.cc:143: error: base class 'class google::protobuf::Message' should be explicitly initialized in the copy constructor 

A similar error can occur when building the ola-examples package:

g++ -DHAVE_CONFIG_H -I. -I..    -Wall -Werror -I/usr/local/include/ 
libola   -g -O2 -MT ola-dmxconsole.o -MD -MP -MF .deps/ola- 
dmxconsole.Tpo -c -o ola-dmxconsole.o ola-dmxconsole.cpp 
cc1plus: warnings being treated as errors 
ola-dmxconsole.cpp: In function ‘void mask()’: 
ola-dmxconsole.cpp:150: error: value computed is not used 
ola-dmxconsole.cpp:156: error: value computed is not used 
ola-dmxconsole.cpp: In function ‘void values()’: 
ola-dmxconsole.cpp:184: error: value computed is not used 
ola-dmxconsole.cpp:188: error: value computed is not used 
ola-dmxconsole.cpp:190: error: value computed is not used 
ola-dmxconsole.cpp:194: error: value computed is not used 
ola-dmxconsole.cpp:197: error: value computed is not used 
ola-dmxconsole.cpp:202: error: value computed is not used 
ola-dmxconsole.cpp:205: error: value computed is not used 
ola-dmxconsole.cpp:208: error: value computed is not used 
ola-dmxconsole.cpp:215: error: value computed is not used 
ola-dmxconsole.cpp:225: error: value computed is not used 
ola-dmxconsole.cpp:226: error: value computed is not used 
ola-dmxconsole.cpp:227: error: value computed is not used 
make[2]: *** [ola-dmxconsole.o] Error 1 

You should be able to prevent this by editing ./src/Makefile.am, removing -Werror and then running autoreconfig && ./configure again.<ref>http://groups.google.com/group/open-lighting/msg/c6d86d03dd74ed5b</ref>

Patching An Art-Net Node

To make the Ubuntu machine act as an Art-Net node first start the OLA daemon with a debug level of 3:

olad -l 3

Then patch the machine for Art-Net output in universe 1 on port 0:

ola_patch -d 1 -p 0 -u 1

Now start ola_dmxconsole for sending some Art-Net data in universe 1:

ola_dmxconsole -u 1

If you run the Art-Net project in Xcode (either with the Simulator or on the iPad) and open the Xcode console window you should see log messages according to your actions in the DMX console.

E.g. try to navigate to a channel with the left and right cursor keys and then increase or decrease the value with the scroll up/down keys.

Sources

<references/>