Overview
The Metis Framework is a set of Objective C API for the HPSDR Metis Ethernet interface. The aim of the library is to provide a simple Cocoa compatible layer for communicating with the High Performance Software Defined Radio (HPSDR) hardware family.
Once it is initialized, the Metis Framework uses delegate callbacks to pass sampled data such as in-phase/quadrature samples from the Digital Down Converter (DDC) and audio microphone or line input. Metis states such as ADC overflow flags, analog voltages, sense bits, PTT, dash and dot state of Morse keys, etc are also sent back to the delegate.
Likewise, the in-phase/quadrature data samples for the Digital Up Converter (DUC), audio samples for the headphones output, and control and command are sent to a Metis device with method calls in the library.
The Programming Guide section has code snippets showing examples of usage. The Metis Framework download package also contains projects and sources for some complete projects, e.g., a bare-bones panadapter that can be modified into a more complete application, and a simple AM, SSB and CW receiver that sends demodulated audio to the Hermes headphones output (DAC).
See below for download instructions.
Requirements
The Metis Framework requires Snow Leopard (Base SDK: Mac OS X 10.6), or newer.
The Metis Framework links against the Cocoa and the vecLib (vector library) Framework, and those frameworks must also be included in any project that uses the Metis Framework. The vecLib.framework is present in the /System/Library/Frameworks folder of shipping Macintoshes.
Usage
Include Metis.framework and vecLib.framework with your Cocoa-based Xcode project.
Follow the instructions here to embed the Metis framework into your application bundle so the user will not need to add it to their /Library/Frameworks folder.
To facilitate easy debugging (e.g., ability to breakpoint the library's code), the Metis Framework is also distributed as a collection of sources in an Metis Framework folder.
Firewalls
Please note that you will need to inform the Mac OS X Firewall to allow network access to applications that accepts data from Metis hardware.
The simplest but least safe procedure is to turn off the Firewall in the Security pref panel of System Preferences.
A safer way is set the "Automatically allow signed software to receive incoming connections" checkbox (shown below) in the Security pref panel of System Preferences (show below), and code sign your application with your Apple Developer ID.
If the application is not code signed and the Firewall is turned on, Mac OS X will momentarily display an alert window asking if you wish to allow an application to accept data packets on the network. Immediately hit the Return/Enter key on the keyboard when the alert window appears (the alert may flash on for less than a second), and Mac OS X will allow that application to accept network traffic in the future. Because this has to be done each time you rebuild your application, the previous two methods are more practical.
License
The sources in the Metis Framework are copyrighted under the Apache software License. By the license, you can freely use pieces of the source code, or modify any parts of it for inclusion into your software, whether commercial or free, without the need to release your own sources. If you publish your sources that includes source code from the Metis Framework, you simply need to include the original attributions and a link to the Apache software license page. There is no restriction whatsoever on the use if you are only including the binary framework.
Download
The Metis volume is in a disk image (dmg) which you can download from here. The disk image includes Metis.framework, and an Xcode project for building the Metis framework that includes the sources for the framework.
Copy the Metis.framework file either to /Library/Frameworks or to ~/Library/Frameworks. Read Usage section above for how to embed the Metis Framework in your own application.
Sample Code
The Examples folder in the downloaded volume includes some sample code.
In order to run the following code examples that reads network data from a Metis device, the computer's Firewall has to be set up to accept network traffic (read Firewalls section above).
Enumerate Network Sample Code
Enumerate Network is an Xcode project that makes use of NetworkInterfaces and NetworkInterface modules in the framework to enumerate the computer's interfaces that have MAC addresses. The output above shows two Ethernet ports (en0 and en1) and a FireWire port (fw0) of a MacPro.
Discover Metis Sample Code
Discover Metis is an Xcode project that makes use of Metis, MetisDiscovery, NetworkInterfaces and NetworkInterface modules to list all Metis devices that are found on the computer's network interfaces (not just one Metis device that is returned by the simple Metis initialization). Shown above is a listing for a single ANAN-10 that is directly connected to the second Ethernet port of a MacPro.
Since the private network lacks a DHCP server, Metis uses an address from the APIPA block (169.254.x.x) with the last two octets of its own MAC address set to the last two octets of its IP address. The board ID 0x01 identifies the Metis device as a Hermes board.
Panadapter Sample Code
Panadapter is a simple panadapter that uses the Metis Framework to obtain data from Hermes, and using vDSP to create trace averaged spectrum plots. A code signed application is included in the Panadapter folder that can be run without compiling the sources.
Radio Sample Code
The Radio sample code is a complete Hermes based SDR receiver that has demodulators for AM, USB, LSB and CW.
It takes 96 ksps I/Q data from a Hermes that is set for one receiver, demodulate the signal, and sends the demodulated audio back as 48 ksps HPSDR formatted frames to feed the headphones jack of Hermes.
The RF attenuator menu uses the Hermes 0-31 dB attenuator at 10 dB steps. The code sample shows how the frequency of the Hermes receiver is set directly from the frequency text field, or by clicking the spectrum NSView, or by using the mouse scroll wheel.
A code signed application is included in the Radio folder that can be run without compiling the sources.
Metis Programmer Sample Code
The Metis Programmer sample code is a working application for downloading new firmware to a Metis device. The description of the application can be found here.
A code signed application is included in the Metis Programmer folder that can be run without compiling the sources.
Metis Bootloader Sample Code
The Metis Bootloader sample code is a working application for downloading new firmware to a Metis device using the Bootloader. The description of the application can be found here.
A code signed application is included in the Metis Bootloader folder that can be run without compiling the sources.
Acknowledgements
Phil Harman VK6PH and Joe Martin K5SO filled in many invaluable details of the Metis and HPSDR data formats and the Hermes and Angelia firmware that are not obvious from the available documents.
Doug K3TZR helped add the additional code that is needed to work with a standalone Metis/Mercury set up.