FHEM on OS X

Most of the the time Fhem is installed on Linux based systems. That could be the reason why most of the HowTos, FAQs and Tips are dealing with Unix issues. As you may know, Apple's OS X is based on Unix as well and it is no big deal to run Fhem on OS X.

HOWTO install Fhem on OS X

Description

This HOWTO describes the necessary steps to install Fhem on a Mac running OS X. Especially Fhem in combination with the FHZ 1000 Device.

Overview

To install Fhem on a Mac, you have to follow these steps:

• Install USB Driver for FHZ 1X00 PC
• Install the C Compiler from XTools
• Install SerialPort Sources from CPAN
• Modify Fhem Makefile
• Install Fhem

USB Driver for FHZ 1X00 PC

FHZ 1000 PC (and the newer version FHZ 1300 PC) is an interface device between the FS20 radio protocol and a PC via an USB interface. FHZ 1000 PC has a fairly straight forward structure based on standard components. It is build around a PIC16F628 processor and uses a FT232AM (FT8U232AM) chip from FTDI for USB communication. The vendor of this chip provides drivers for Mac OS X 10.3, 10.4, 10.5 and 10.6. Please download and install the most recent version from their website: FTDIUSBSerialDriver

When the computer has rebooted, plug in the device and check if the device is installed properly. Take a look at the the OS X System Logfile (/var/log/system.log). The FHZ1000 device should recognize by the system as follows:

kernel [0]: FTDIUSBSerialDriver:		0	403f06f start - ok

If not, please check the device and the USB cable on a different system (e.g. Linux > 2.6).

After that, you will see two entries in the /devdirectory. To check this, open the OS X Terminal Application and execute the following command:

$ls /dev/cu.*
/dev/cu.usbserial-xxxxxxxx
$ls /dev/tty.*
/dev/tty.usbserial-xxxxxxxx

where xxxxxxxxis either the device's serial number.

Now you can talk to the box via /dev/tty.usbserial-xxxxusing the FS20 Protocol.

Symbolic Link to ttyUSB0

Because Fhem is talking to the device using /dev/ttyUSB0, for better handling you should define a symbolic link: Open the OS X Terminal Application and execute the following command:

$ sudo ln -s /dev/tty.usbserial-xxxxxx /dev/ttyUSB0

NOTE!: Under specific circumstances, the symlink disappears after a reboot. If someone can solve this issue or know the reason for that, please edit this paragraph!

The issue can simply be fixed by specifying the /dev/cu.usbmodem-xxxx instead of /dev/ttyUSB0 as the serial device in fhem.cfg.

OS X will give each device a unique device name. a device that is unplugged and reconnected will receive the same device file. so these unique names should be used in fhem instead of the symbolic links.

GNU C Compiler

Apple's brand-name for the 'developer tools' is 'XCode Tools', it is GCC and a few other bits and bobs. To install it is a simple matter, you simply install the package on your OS X DVD. I'm led to believe the CD version of Mac OS X has a dedicated CD called 'X-Code Tools'. If you have lost the DVD already then you can download X-code tools from Apple's website. Although you must sign-in to be able to to get the file.

NOTE: Always make sure to install the latest available version of Xcode Tools for your Mac OS X release; using outdated versions of Xcode Tools may cause port install failures. Also note that Xcode Tools are not updated via Mac OS X's Software Update utility.

• Run the Xcode Tools package installer.
• Click the button Customize, expand the Applications category and click the check box beside X11 SDK to add it to the default items.
• Ensure that the option for command line development, which is labeled Unix Development in the Xcode 3.x installer, is checked.

SerialPort Perl Modul

SerialPort for Linux is a user interface to Serial API calls. The module provides an object-based user interface essentially identical to the one provided by the Win32::SerialPort module. To install this modul you can get the right sources from the CPAN Website.

Open the OS X Terminal Application and execute the following command:

sudo perl –MCPAN –e shell

If you do this the first time, Perl may ask you a few questions... just enter YES. At the end you will read something like cpan shell -- CPAN exploration and modules installation (v1.9205). Within the CPAN Shell, you have to execute the following two commands:

[cpan[1]>] install Bundle::CPAN
[cpan[1]>] install Device::SerialPort
[cpan[1]>] quit

Some testing

Now you should be ready to use the Module Device::SerialPort. If have already configured your Hardware (CUN, CUL, FHZ1000...) you can check the functionality with a little Perl script: elv.pl

As a result, you will get something link this:

# ./elv.pl 
Sending ...8106c98602011f64 
Got: 810bc93b01021f0278075c44f8 [0]
Sending ...810804afc90184570208 Result: 10
Got: 810fc9ae010284010807f8136e3118 [1]
Got: 4c09 [2]

Install Fhem

Download the most recent version of Fhem from Rudi's Website. Extract the archive and install the Software as described on the Website.

You most likely will have fhem installed in some custom directory, so you need to adapt the first lines in the Makefile, for example change to:

BINDIR=/usr/local/bin
MODDIR=/usr/local/share/fhem
VARDIR=/var/log/fhem
DOCDIR=/usr/local/share/doc/fhem
MANDIR=/usr/local/share/man/man1
ETCDIR=/usr/local/etc

Open the OS X Terminal Application and execute the following command:

sudo make install-pgm2

Comment fhainz:

sudo make install-pgm2 won't work. --> make: *** No rule to make target `install-pgm2'. Stop.

This

 sudo make install

works on OSX 10.9.1

Modify fhem.cfg

You have to modify the main configuration file on your personal effort. There are many samples an descriptions on the web...

Run Fhem

To make sure that Fhem Server is starting on every Reboot, just place a start script under /Library/StartupItems.

Create a startup script:

Launchd

The more modern way would be to create a lauch daemon like the following example.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
    "[http://www.apple.com/DTDs/PropertyList-1.0.dtd http://www.apple.com/DTDs/PropertyList-1.0.dtd]">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>de.fhemwiki.fhem</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/perl</string>
        <string>/usr/local/bin/fhem.pl</string>
        <string>/usr/local/etc/fhem.cfg</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>UserName</key>
    <string>YOURUSERNAMETORUNFHEM</string>
</dict>
</plist>

Save this to a file named de.fhemwiki.fhem.plist in the directory /Library/LaunchDaemons/ For this to work, you must add "attr global nofork 1" to fhem.cfg.

You might run into some permission problems if not running fhem as "root", but running as root is not a good idea, so go out and fix the file permissions for the user fhem runs as.