Installation/MacOSX

The task of supporting Paparazzi on Apple MacOS X is ongoing as the project evolves and the more people adapt it the process will be streamlined. Presently it is known that Paparazzi will install on OSX versions 10.5.8, 10.6, 10.6.2 and 10.6.6.

Intro

Would it not be great to also be able to run Paparazzi from your shiny Apple Mac? Well, this page explains how you can manage to do just that.

Installing from source

The tools that are required to work with paparazzi on a Mac are installed from MacPorts. All of the commands are given by terminal commands, please open your terminal first.

In case you already have MacPorts installed, it is advised to run the following steps before proceeding:

1. check that /opt/local/bin is the first entry in your PATH, easy to check by giving the following command

env

2. Then give the following command to make sure your ports are up-to-date

sudo port selfupdate && sudo port upgrade outdated

..great, you now can run the installation steps starting from step 3 below.

If you don't already have MacPorts installed run the following steps:

1. Install the latest XCode http://developer.apple.com/technologies/tools/xcode.html
2. Install MacPorts from http://www.macports.org/install.php
3. Edit the file /opt/local/etc/macports/sources.conf and above the rsync://... line add rsync://rsync.paparazziuav.org/macports/ports/ It is important that this line comes before the path to the standard ports as some of the Paparazzi ports are intended to replace the standard versions. The file is write protected so it will be necessary to be root in order to edit it. The simplest way is to open a terminal window and use nano thus:

   sudo nano /opt/local/etc/macports/sources.conf

4. Now update the available ports with the command:

   sudo port selfupdate

5. If you do not have your own copy of the paparazzi source then you now need to install paparazzi:

   sudo port install paparazzi

   OR if you do already have your own copy of the paparazzi source and you want to keep in then the tools required by paparazzi can be installed with the command

   sudo port install paparazzi-tools

6. ...Then go and have lunch, get a coffee, get some sleep. This will probably take a long time.
If you want to follow the standard Paparazzi Git install then the prerequisite software can be installed by running the command sudo port install paparazzi-tools

Troubleshooting

If you continually experience problems installing paparazzi or paparazzi-tools then it may be that you have some other conflicting software installed. i.e. an old version of a library in /usr.

One way to work around issues relating to prior MacPort installs that has been found is to clean out everything MacPorts has installed and install from scratch using the latest MacPorts

1. sudo port -f uninstall installed
2. sudo port clean --all uninstalled
3. sudo port selfupdate
4. sudo port -f install paparazzi-tools or sudo port -f install paparazzi

This was in fact the process used to check that the code installed on a clean machine.

Upgrading to Lion

If you already have MacPorts and Paparazzi installed and running and you then upgrade to Lion you'll probably find that some things are broken. (make can't be found for example) To remedy this situation you need to do the following:

1. Upgrade Xcode to the Lion version. (App Store --> Search for Xcode and install)
2. Install the Lion version of MacPorts from http://www.macports.org/install.php
3. sudo port -f uninstall installed
4. sudo port clean --all uninstalled
5. sudo port selfupdate
6. sudo port -f install paparazzi-tools or sudo port -f install paparazzi

At the time of writing there was a problem with the eggdbus port the died. A bug was raised for this issue. Simply running the install step again seems to be enough to work around this issue.

If you use a USB to serial converter that isn't based on the FTDI chipset then you may also find that your USB to Serial driver needs to be updated.

1. Start console
2. Plug in your USB to serial converter

You may get a message similar to this Jul 26 23:14:48 Bernies com.apple.kextd[10]: Can't load /System/Library/Extensions/osx-pl2303.kext - no code for running kernel's architecture.

If you are fortunate enough to have a USB to serial converter that is using the PL2303 chipset then the Prolific driver should sort you out. Installation instructions are included in the readme.txt and are well worth following.

Keeping source files for debugging

If you wish to debug code using the source install then you'll find that many of the source files for the libraries are missing.

This is because MacPorts cleans up the build artifacts and source files after the installation is complete. This behaviour can be changed by adding the -k option to the port command.

For example:

 sudo port -k install paparazzi-tools

This will result in all of the source and build artefact files being left on the hard disk.

Should you later wish to clean up these files you can do so with the clean command.

For example:

 sudo port clean installed

Installation using the binary installer

1. Install the latest XCode http://developer.apple.com/technologies/tools/xcode.html
2. Download the paparazzi binary installer from http://download.paparazziuav.org/darwin/
3. Install paparazzi by double clicking on the downloaded file paparazzi.mpkg


If you want to follow the standard Paparazzi Git install then the prerequisite software can be installed by downloading the paparazzi-tools binary installer from http://TODO find a place to host this file and installing the tools by doublclicking on the downloaded file paparazzi-tools.mpkg

Running Paparazzi

Paparazzi can be started in the usual way

cd ~/paparazzi
./paparazzi

Changing the GTK look and feel

Run /opt/local/bin/switch2 to select a different theme. More detailed instructions can be found at http://gtk.php.net/manual/en/html/tutorials/tutorials.installation.macosx-stepbystep.html

Additional themes can be downloaded from http://art.gnome.org/themes/gtk2

USB Drivers for Telemetry

No drivers need to be installed in order to program either the STM32 based or LPC2148 based autopilot boards (ie TINY, TWOG, Booz, Lisa/L, Lisa/M) using a USB port. However telemetry between the vehicle and ground control station requires a modem. On an Apple Mac this will generally be connected to a USB port. Whatever modem is used it will be necessary to load drivers that allow Paparazzi to communicate with the modem. It is not possible to describe all possible modems and their configuration. However the most commonly used chipset for USB to serial communication is produced by FTDI. Below is described the installation of the FTDI drivers. This can be used as a guide for installing drivers for modems using other chipsets.


FTDI drivers can be downloaded from FTDI

The device will probably become available as something like /dev/tty.usbserial-000013FD when connected. Note that different USB ports get different addresses. When connecting to another port the same device came up as /dev/tty.usbserial-000014FA

Since Paparazzi is currently configured to use /dev/ttyUSB0 it's easiest to just create a link to the required device.

1. Remove all USB devices from the computer and run the command ls -l /dev/*usb* /dev/*USB* hopefully this will not list anything
2. Plug in your radio and repeat the command ls -l /dev/*usb* /dev/*USB* this should now list the serial port that the radio has been connected to. In my case I get

       ls -l /dev/*usb* /dev/*USB*

   crw-rw-rw- 1 root wheel 11, 27 20 Jan 14:38 /dev/cu.usbserial-000013FD

   crw-rw-rw- 1 root wheel 11, 26 20 Jan 14:38 /dev/tty.usbserial-000013FD

3. Next we need to create a symbolic link to the tty.usbserial device listed to /dev/ttyUSB0 in my case the command is sudo ln -s /dev/tty.usbserial-000013FD /dev/ttyUSB0
4. To check that everything is correct run the first command again ls -l /dev/*usb* /dev/*USB* and you should get something like this

       ls -l /dev/*usb* /dev/*USB*

   crw-rw-rw- 1 root wheel 11, 27 20 Jan 14:38 /dev/cu.usbserial-000013FD

   crw-rw-rw- 1 root wheel 11, 26 20 Jan 14:38 /dev/tty.usbserial-000013FD

   lrwxr-xr-x 1 root wheel 0 20 Jan 14:42 /dev/ttyUSB0 -> /dev/tty.usbserial-000013FD


Once the FTDI driver (kernel extension) is loaded it takes over for all FTDI connections. This means that it will not be possible to program the Lisa/L or Lisa/M boards while the driver is loaded.

To unload the driver use the command

sudo kextunload/System/Library/Extensions/FTDIUSBSerialDriver.kext

This should not give an error. if it does then try again a few times after quitting programs that may have used the connection. If the driver still fails to unload then a reboot may be required.

When it comes time to connect the modem again you'll again need the driver loaded. This can be done with the complementary command

sudo kextload/System/Library/Extensions/FTDIUSBSerialDriver.kext

Workaround for Issues with errors (Device busy) when trying to program a Lisa/L

Programming the Lisa on OS X

The problem: The "default" vendor id and product id for the ftdi device on Lisa is the same one used by all the manufacturers of clone usb-serial interfaces. This isn't an issue on Linux because of the udev rules file we use does not load the ftdi drivers for lisas programming interface. Windows and Mac OS X don't use this file so they can only use vendor id and product id. So as soon as you plug in Lisa they load USB->serial port drivers for the two ports they believe are on Lisa causing a conflict. The programming of Lisa happens through a different mechanism and does not want the programming interface of Lisa to be taken by the FTDI driver which has already been loaded. For OS X there is a hack we can do that makes it better until we can get vendor and product ids sorted out. It involves modifying the /System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist file. We change it so only the first of the two serial interfaces is loaded. The second is not as it is the programming interface.

The File (edit with a text editor):

/System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist

Here is a diff between a "vanilla OS X" and one that has been modified (Essentially below was removed):

quadzilla:Contents root# diff ~/Info.plist Info.plist 
1784,1805d1783
< 		<key>FT2232C_B</key>
< 		<dict>
< 			<key>CFBundleIdentifier</key>
< 			<string>com.FTDI.driver.FTDIUSBSerialDriver</string>
< 			<key>ConfigData</key>
< 			<dict>
< 				<key>LatencyTimer</key>
< 				<integer>2</integer>
< 			</dict>
< 			<key>IOClass</key>
< 			<string>FTDIUSBSerialDriver</string>
< 			<key>IOProviderClass</key>
< 			<string>IOUSBInterface</string>
< 			<key>bConfigurationValue</key>
< 			<integer>1</integer>
< 			<key>bInterfaceNumber</key>
< 			<integer>1</integer>
< 			<key>idProduct</key>
< 			<integer>24592</integer>
< 			<key>idVendor</key>
< 			<integer>1027</integer>
< 		</dict>
1830,1853d1807
< 		<key>FT2232H_B</key>
< 		<dict>
< 			<key>CFBundleIdentifier</key>
< 			<string>com.FTDI.driver.FTDIUSBSerialDriver</string>
< 			<key>ConfigData</key>
< 			<dict>
< 				<key>LatencyTimer</key>
< 				<integer>2</integer>
< 			</dict>
<  			<key>IOClass</key>
< 			<string>FTDIUSBSerialDriver</string>
< 			<key>IOProviderClass</key>
< 			<string>IOUSBInterface</string>
< 			<key>bConfigurationValue</key>
< 			<integer>1</integer>
< 			<key>bInterfaceNumber</key>
< 			<integer>1</integer>
< 			<key>bcdDevice</key>
< 			<integer>1792</integer>
<  			<key>idProduct</key>
< 			<integer>24592</integer>
< 			<key>idVendor</key>
< 			<integer>1027</integer>
< 		</dict>

Once you have edited the file

- sudo kextunload /System/Library/Extensions/FTDIUSBSerialDriver.kext/
- sudo kextload /System/Library/Extensions/FTDIUSBSerialDriver.kext/

To reload the driver or you can just reboot.

It is expected as Paparazzi moves to supporting more operating systems that unique product and vendor ids will be obtained thus removing the need for this step.

Installing FlightGear

FlightGear has been packaged for use on OS X. This package can be downloaded from: http://macflightgear.sourceforge.net/home/downloads/

There are several packages available. Recently, FlightGear 2.4.0 was released. A binary for OS X is available, and seems to work properly on Snow Leopard (OS X 10.6.8). The binary released March 18, 2010 (2.0.0) installs and runs properly on OS X 10.6. Follow the directions here for installation and basic usage. Additional documentation can be found here. The Development Snapshot from August 21, 2010 does not seem as stable (did not work properly when tried on one machine).

There is a patch available for crashes encountered on the splash screen, as detailed here: http://macflightgear.sourceforge.net/a-patch-that-prevents-fg-200-from-crash-on-launch-is-available


Screenshot of FlightGear launch gui in OS X with options for visualizing Paparazzi simulations

Once FlightGear is installed, the GUI launcher can be used to set common options. By clicking on the Advanced Features arrow, one can gain access to many more options as well as an interface to specify command line options (the Others tab). This is where one can specify the flight dynamics model and network connectivity required for visualizing Paparazzi simulations as described on the Simulation page.




• In Paparazzi Center, add to the simulator command the -fg option plus the IP address of the machine running flightgear in this case the loopback interace is used as Flightgear and Paparazzi are running on the same machine:

.../sw/simulator/launchsitl -a TJ1 -fg 127.0.0.1 -boot -norc

Note TJ1 is the name of the aircraft you must substitute this with the name of your aircraft.

• Launch Flight Gear with the following set in the others tab under advanced settings:

--fdm=null --native-gui=socket,in,30,,5501,udp





Screenshot of Flightgear visualizing the default Microjet simulation in OS X (not the default Muret, FR location)

If it is night in FlightGear and you wish to view the simulation in daylight, follow the instructions on the Simulation page.

Simulations Using JSBSim

JSBSim is an open-source flight dynamics and control software library. It can provide a more realistic simulation environment over the basic built-in Paparazzi simulator. See the Simulation page for background information and how to run a normal simulation. After this can be done in a satisfactory manner, follow the steps below to utilize the JSBSim flight dynamics model.

How to run JSBSim simulations:

Please see Simulation#JSBSim for instructions on how to use the JSBSim FDM in simulations, with the following changes:

• Install the JSBSim libraries onto your system. This should already be installed with paparazzi-tools, but if it isn't:

 $ sudo port install jsbsim

It uses code from the cvs repo, so it should be the most up-to-date source.

• Compile your airframe for the jsbsim target. Launch the GCS and Server as per normal simulation. The simulation needs the -jsbsim option like this:

 <paparazzi home directory>/sw/simulator/launchsitl  -a <aircraft_name> -jsbsim -boot -norc

The JSBSim simulation can be used with FlightGear visualization as described above, by adding the -fg 127.0.0.1 option in addition, like this:

 <paparazzi home directory>/sw/simulator/launchsitl  -a <aircraft_name> -jsbsim -boot -norc -fg 127.0.0.1

For information on using an optional initialization file for the simulation initial conditions and how to set the launch velocity, please see Simulation#Using_Optional_Parameters.

Differences with the Linux version

This section is intended to document all the subtle differences between Linux and Mac OS X versions of Paparazzi.

Change of text editor

The default editor in Linux is gedit, but in OS X, it is open, which simply uses whatever the default program for opening .xml files is setup.

Ivy subnet mask

On Linux, the Ivy submask is 127.255.255.255

On Mac OS X, the Ivy submask is 224.255.255.255




In C applications, such as tmtc/c_ivy_client_example_1.c, this should be set adaptively by something like:

 #ifdef __APPLE__
  printf("Mac OS, network submask: 224.255.255.255\n");
  IvyStart("224.255.255.255");
 #else
  printf("NO Mac OS, network submask: 127.255.255.255\n");
  IvyStart("127.255.255.255");
 #endif


Is there a better way to do this?