This post is accompanied by a sample application that can be found on GitHub. Feel free to clone the repository and try it out yourself.

The UI

We will not discuss the UI elements in detail, but will focus instead on calculations and Java code. The code below is from the sample application's layout file. The layout contains three TextView elements for displaying magnetic heading, true heading and magnetic declination values. The ImageView contains an image resembling a compass. The image will be programmatically rotated with animation, based on magnetic heading value.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity"
    android:background="#e7cf8a"
    >

    <LinearLayout
        android:id="@+id/linear_layout_values"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintBottom_toTopOf="@+id/image_compass"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintVertical_chainStyle="spread">

        <TextView
            android:id="@+id/text_view_magnetic_declination"
            android:layout_width="0dp"
            android:layout_height="wrap_content"
            android:layout_weight="1"
            android:gravity="center"
            android:textStyle="bold" />

        <TextView
            android:id="@+id/text_view_heading"
            android:layout_width="0dp"
            android:layout_height="wrap_content"
            android:layout_weight="1"
            android:gravity="center"
            android:textStyle="bold" />

        <TextView
            android:id="@+id/text_view_true_heading"
            android:layout_width="0dp"
            android:layout_height="wrap_content"
            android:layout_weight="1"
            android:gravity="center"
            android:textStyle="bold" />

    </LinearLayout>

    <ImageView
        android:id="@+id/image_compass"
        android:layout_width="0dp"
        android:layout_height="wrap_content"
        android:adjustViewBounds="true"
        android:src="@drawable/compass"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/linear_layout_values"
        app:layout_constraintWidth_percent="0.8" />

</androidx.constraintlayout.widget.ConstraintLayout>

The Sensors & Tilt Compensation

A magnetometer is a sensor used for measuring magnetic fields. A magnetometer can measure Earth's magnetic field if not influenced by a strong nearby magnetic field. The sensor provides magnetic field strength along three axes X, Y and Z in micro Tesla (μT).

Earth's magnetic field is parallel to Earth's surface. If a device is parallel to Earth's surface, heading can be measured by using a magnetometer's X and Y components. However if the device is tilted, the heading value will no longer be accurate and tilt compensation should be performed by utilizing an accelerometer.

An accelerometer is a sensor that measures acceleration along the three axes X, Y and Z in meter per second squared (m/s²). Accelerometer readings will be used for magnetometer correction.

Obtaining Sensor Readings on Android

Sensor readings are obtained through the SensorManager API. Create a global SensorManager object and initialize it in the activity's OnCreate method.

private SensorManager sensorManager;

...

sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);

In the OnResume method, register listeners on accelerometer and magnetic field sensors. We should also unregister the listeners in the OnPause method in case the application is closed.

    @Override
    protected void onResume() {
        super.onResume();

        Sensor accelerometer = sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER);
        if (accelerometer != null) {
            sensorManager.registerListener(this, accelerometer,
                    SensorManager.SENSOR_DELAY_GAME, SensorManager.SENSOR_DELAY_GAME);
        }

        Sensor magneticField = sensorManager.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD);
        if (magneticField != null) {
            sensorManager.registerListener(this, magneticField,
                    SensorManager.SENSOR_DELAY_GAME, SensorManager.SENSOR_DELAY_GAME);
        }
    }
    
    
    @Override
    protected void onPause() {
        super.onPause();
        sensorManager.unregisterListener(this);
    }

Following that, implement the interface SensorEventListener and let Android Studio automatically implement the interface's method. The implemented method onSensorChanged will be called whenever new sensor values are received. Updated sensor values can be obtained from the SensorEvent argument.

In the code snippet below, we are receiving updated sensor values, passing them to our low-pass filter, then calling the updateHeading() function. The low-pass filter and heading calculation will be discussed in upcoming sections.

    private final float[] accelerometerReading = new float[3];
    private final float[] magnetometerReading = new float[3];

	...
    
        @Override
    public void onSensorChanged(SensorEvent event) {
        if (event.sensor.getType() == Sensor.TYPE_ACCELEROMETER) {
            //make sensor readings smoother using a low pass filter
            CompassHelper.lowPassFilter(event.values.clone(), accelerometerReading);
        } else if (event.sensor.getType() == Sensor.TYPE_MAGNETIC_FIELD) {
            //make sensor readings smoother using a low pass filter
            CompassHelper.lowPassFilter(event.values.clone(), magnetometerReading);
        }
        updateHeading();
    }

Calculating Magnetic Heading

There are several methods for tilt compensation. We will use vector cross product method to obtain a tilt compensated heading angle (azimuth).

Magnetic heading is obtained by performing the following:

• Calculating the cross product of the magnetic field vector and the gravity vector to get a new vector H
• Normalizing the values of the resulting vector H and of the gravity vector
• Calculating the cross product of the gravity vector and the vector H to get a new vector M pointing towards Earth's magnetic field
• Using arctangent to obtain heading in radians
• Converting the angle from radians to degrees
• Mapping the heading angle from [-180,180] range to [0, 360] range

The functions below implement these steps.

    public static float calculateHeading(float[] accelerometerReading, float[] magnetometerReading) {
        float Ax = accelerometerReading[0];
        float Ay = accelerometerReading[1];
        float Az = accelerometerReading[2];

        float Ex = magnetometerReading[0];
        float Ey = magnetometerReading[1];
        float Ez = magnetometerReading[2];

        //cross product of the magnetic field vector and the gravity vector
        float Hx = Ey * Az - Ez * Ay;
        float Hy = Ez * Ax - Ex * Az;
        float Hz = Ex * Ay - Ey * Ax;

        //normalize the values of resulting vector
        final float invH = 1.0f / (float) Math.sqrt(Hx * Hx + Hy * Hy + Hz * Hz);
        Hx *= invH;
        Hy *= invH;
        Hz *= invH;

        //normalize the values of gravity vector
        final float invA = 1.0f / (float) Math.sqrt(Ax * Ax + Ay * Ay + Az * Az);
        Ax *= invA;
        Ay *= invA;
        Az *= invA;

        //cross product of the gravity vector and the new vector H
        final float Mx = Ay * Hz - Az * Hy;
        final float My = Az * Hx - Ax * Hz;
        final float Mz = Ax * Hy - Ay * Hx;

        //arctangent to obtain heading in radians
        return (float) Math.atan2(Hy, My);
    }


    public static float convertRadtoDeg(float rad) {
        return (float) (rad / Math.PI) * 180;
    }

    //map angle from [-180,180] range to [0,360] range
    public static float map180to360(float angle) {
        return (angle + 360) % 360;
    }

Implementing a Low-Pass Filter for Smoother Sensor Data

Using sensor data directly results in jittery heading values and compass rotation. Different filters can be used for obtaining smoother sensor data. However, filter algorithms can be very complex. We will implement a simple low-pass filter that provides us with nice and smooth results. Check the references section for further discussion on filters.

    //0 ≤ ALPHA ≤ 1
    //smaller ALPHA results in smoother sensor data but slower updates
    public static final float ALPHA = 0.15f;
    
    public static float[] lowPassFilter(float[] input, float[] output) {
        if (output == null) return input;

        for (int i = 0; i < input.length; i++) {
            output[i] = output[i] + ALPHA * (input[i] - output[i]);
        }
        return output;
    }

Magnetic Declination and True Heading

Magnetized compass needles and magnetometers point towards Earth's magnetic field. Thus, magnetic declination value is required to obtain true heading. Magnetic declination is defined as the angle between magnetic north and true north. Declination is positive east of true north and negative when west.

true heading = magnetic heading + magnetic declination

Magnetic declination varies over time and with location. The change of magnetic field was observed over a period of years and two Geomagnetic models were created: International Geomagnetic Reference Field (IGRF) and World Magnetic Model (WMM). We will use the open source Java implementation of the WMM created by Los Alamos National Laboratory to calculate magnetic declination. WMM's coefficients have been updated in 2020 and are valid for five years. Longitude, latitude and altitude are required to calculate magnetic declination.

    public static float calculateMagneticDeclination(double latitude, double longitude, double altitude) {
        TSAGeoMag geoMag = new TSAGeoMag();
        return (float) geoMag
                .getDeclination(latitude, longitude, geoMag.decimalYear(new GregorianCalendar()), altitude);
    }

Getting Last Known Location

To obtain longitude, latitude and altitude, we will use the FusedLocationProviderClient to get the user's last known location. This client is provided by Google Play services. Check the developer guides in the references section for more details on setting up and using the FusedLocationProviderClient.

Make sure to include Google Play location services as a dependency in the build.gradle file, and to include the required location permissions in the AndroidManifest.xml file.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Create and initialize a FusedLocationProviderClient object. However before requesting location data, we have to check if user has granted location permissions to the application. If permissions are not already granted, a prompt should be presented to the user requesting location permissions.

        fusedLocationClient = LocationServices.getFusedLocationProviderClient(this);

        //check if we have permission to access location
        if (ContextCompat.checkSelfPermission(
                this, Manifest.permission.ACCESS_FINE_LOCATION) ==
                PackageManager.PERMISSION_GRANTED) {
            //fine location permission already granted
            getLocation();
        } else {
            //if permission is not granted, request location permissions from user
            ActivityCompat.requestPermissions(this,
                    new String[]{Manifest.permission.ACCESS_FINE_LOCATION},
                    REQUEST_PERMISSION_FINE_LOCATION);
        }

The method onRequestPermissionsResult should also be implemented to handle the location permissions result provided by the user. If the user rejects the permission prompt, an error message will be displayed.

    @Override
    public void onRequestPermissionsResult(int requestCode, String[] permissions,
                                           int[] grantResults) {
        if (requestCode == REQUEST_PERMISSION_FINE_LOCATION) {
            //if request is cancelled, the result arrays are empty.
            if (grantResults.length > 0 &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                //permission is granted
                getLocation();
            } else {
                //display Toast with error message
                Toast.makeText(this, R.string.location_error_msg, Toast.LENGTH_LONG).show();
            }
        }
    }

If location permissions were granted, the function getLocation will be called to retrieve the required location data from the FusedLocationProviderClient, and to calculate magnetic declination.

    @SuppressLint("MissingPermission") //suppress warning since we have already checked for permissions before calling the function
    private void getLocation() {
        fusedLocationClient.getLastLocation()
                .addOnSuccessListener(this, new OnSuccessListener<Location>() {
                    @Override
                    public void onSuccess(Location location) {
                        // Got last known location. In some rare situations this can be null.
                        if (location != null) {
                            isLocationRetrieved = true;
                            latitude = (float) location.getLatitude();
                            longitude = (float) location.getLongitude();
                            altitude = (float) location.getAltitude();
                            magneticDeclination = CompassHelper.calculateMagneticDeclination(latitude, longitude, altitude);
                            textViewMagneticDeclination.setText(getString(R.string.magnetic_declination, magneticDeclination));
                        }
                    }
                });
    }

Wrapping it All Up

Now that we have written all supporting code, what remains is calculating heading and updating the UI accordingly. The function updateHeading is called by onSensorChanged on every sensor value change event. It calculates magnetic heading, then checks if location data is available and calculates true heading. Finally, TextView elements are updated, and the compass image is rotated with animation to simulate a real compass.

    private void updateHeading() {
        //oldHeading required for image rotate animation
        oldHeading = heading;

        heading = CompassHelper.calculateHeading(accelerometerReading, magnetometerReading);
        heading = CompassHelper.convertRadtoDeg(heading);
        heading = CompassHelper.map180to360(heading);

        if(isLocationRetrieved) {
            trueHeading = heading + magneticDeclination;
            if(trueHeading > 360) { //if trueHeading was 362 degrees for example, it should be adjusted to be 2 degrees instead
                trueHeading = trueHeading - 360;
            }
            textViewTrueHeading.setText(getString(R.string.true_heading, (int) trueHeading));
        }

        textViewHeading.setText(getString(R.string.heading, (int) heading));

        RotateAnimation rotateAnimation = new RotateAnimation(-oldHeading, -heading, Animation.RELATIVE_TO_SELF, 0.5f, Animation.RELATIVE_TO_SELF, 0.5f);
        rotateAnimation.setDuration(500);
        rotateAnimation.setFillAfter(true);
        imageViewCompass.startAnimation(rotateAnimation);
    }

References

• SensorManager API Android open source implementation
• W3 Absolute Orientation Sensor
• Matlab E-Compass Algorithms
• Thom Nichols - Smoothing sensor data with a low pass filter
• W3 Low and high pass filters
• NOAA - Magnetic Declination
• NOAA - Geomagnetic Models Software Implementation
• Android Location Developer Guide
• Android Permissions Developer Guide

Icecast is an open source media streaming server that can stream both audio and video across a network. It is very versatile and customizable. It can be used for running live podcasts or for hosting internet radio stations.

In this guide, I will share my experience of setting up an HTTPS audio stream over Icecast. The guide will assume that you are running Ubuntu 18.04.

The Architecture

Icecast requires a source client that sends a bitstream to a mountpoint. Listeners can listen to the stream by accessing these mountpoints.

Image from wiki.xiph.org

We will discuss setting up source clients later.

Installing Icecast

The Icecast package included in Ubuntu 18.04 repositories is not compiled with HTTPS support. Thus, we will add the official Xiph repository which includes the latest Icecast package compiled with HTTPS support.

1. Add the Xiph repository.

sudo sh -c "echo deb http://download.opensuse.org/repositories/multimedia:/xiph/xUbuntu_18.04/ ./ >>/etc/apt/sources.list.d/icecast.list"

2. Add the multimedia signing key as a trusted key.

wget -qO - http://icecast.org/multimedia-obs.key | sudo apt-key add -

3. Update apt package indexes.

sudo apt-get update

4. Install Icecast.

sudo apt-get install icecast2

5. Setup SSL.

This section will assume that you already have a SSL certificate from Let's Encrypt with certbot configured for certificate auto renewal. Certbot setup varies slightly depending on whether the server is already running a web server (Apache, Nginx, etc.) or not. The instructions at EFF are straightforward on how to setup certbot based on different scenarios.

Note: You can choose to skip this step and run Icecast without enabling SSL.

Icecast requires an SSL certificate file that contains both the private and public key. Thus, we will concatenate the keys generated by Let's Encrypt, and then move them to our Icecast directory. After that, we will change the ownership of the new key file to Icecast user and group. This will allow the Icecast server to access the new certificate file.

cat /etc/letsencrypt/live/talesofcode.com/fullchain.pem /etc/letsencrypt/live/talesofcode.com/privkey.pem > /etc/icecast2/concat.pem

chown icecast2:icecast /etc/icecast2/concat.pem

Certificates issued by Let's Encrypt are valid for 90 days, and are automatically renewed by certbot. Thus, we should add a post hook to certbot that automatically combines the private and public keys for Icecast upon certificate renewal.

The following line should be added to the file /etc/letsencrypt/renewal/talesofcode.com.conf under the [renewalparams] section:

post_hook = cat /etc/letsencrypt/live/talesofcode.com/fullchain.pem /etc/letsencrypt/live/talesofcode.com/privkey.pem > /etc/icecast2/concat.pem && service icecast2 restart

Configuring Icecast

We will now configure Icecast by editing the Icecast configuration file.

nano /etc/icecast2/icecast.xml

The parameters below are the main parameters required to get us up and running:

• <source-password>: the plaintext password used by source clients to connect to Icecast.
• <admin-password>: the plaintext password used for web administration functions.
• <port> and <ssl> parameters under the <listen-socket> parameter.
• mountpoint parameters under mount.
• <ssl-certificate> parameter under paths.

Refer to Icecast documentation for details on all supported parameters.

The snippet below contains the full icecast.xml file with all parameters set.

<icecast>
    <location>Earth</location>
    <admin>icemaster@localhost</admin>

    <limits>
        <clients>12000</clients>
        <sources>2</sources>
        <queue-size>524288</queue-size>
        <client-timeout>30</client-timeout>
        <header-timeout>15</header-timeout>
        <source-timeout>10</source-timeout>
        <burst-on-connect>1</burst-on-connect>
        <burst-size>65535</burst-size>
    </limits>

    <authentication>
        <!-- Sources log in with username 'source' -->
        <source-password>secret-pass-here</source-password>
        <!-- Relays log in with username 'relay' -->
        <relay-password>disabled</relay-password>

        <!-- Admin logs in with the username given below -->
        <admin-user>ice-admin</admin-user>
        <admin-password>secret-pass-here</admin-password>
    </authentication>

    <hostname>talesofcode.com</hostname>

    <!-- You may have multiple <listener> elements -->
    <listen-socket>
        <port>8443</port>
        <ssl>1</ssl>
    </listen-socket>
    
	
    <http-headers>
        <header name="Access-Control-Allow-Origin" value="*" />
    </http-headers>


    <!-- Mountpoints-->
    <mount>
        <mount-name>/stream.mp3</mount-name>
        <stream-name>Tales of Code Live Stream</stream-name>
        <stream-description>Tales of Code Live Stream</stream-description>
        <bitrate>192</bitrate>
        <type>audio/mpeg</type>
    </mount>

    <fileserve>1</fileserve>

    <paths>
        <!-- basedir is only used if chroot is enabled -->
        <basedir>/usr/share/icecast2</basedir>

        <!-- Note that if <chroot> is turned on below, these paths must both
             be relative to the new root, not the original root -->
        <logdir>/usr/share/icecast2/logs</logdir>
        <webroot>/usr/share/icecast2/web</webroot>
        <adminroot>/usr/share/icecast2/admin</adminroot>
        <!-- <pidfile>/usr/share/icecast2/icecast.pid</pidfile> -->

        <alias source="/" destination="/status.xsl"/>
        <!-- The certificate file needs to contain both public and private part.
             Both should be PEM encoded. -->
        <ssl-certificate>/etc/icecast2/concat.pem</ssl-certificate>
    </paths>

    <logging>
        <accesslog>access.log</accesslog>
        <errorlog>error.log</errorlog>
        <loglevel>3</loglevel> <!-- 4 Debug, 3 Info, 2 Warn, 1 Error -->
        <logsize>10000</logsize>
    </logging>

    <security>
        <chroot>0</chroot> <!-- chroot disabled -->
        <changeowner>
            <user>icecast2</user>
            <group>icecast</group>
        </changeowner> 
    </security>
</icecast>

Save and close the xml file. You should now be able to start the Icecast server using the command below:

icecast -b -c /etc/icecast2/icecast.xml

If all is well, Icecast status page should now be accessible from a web browser on port 8443 https://your-domain-or-ip:8443. Make sure that the port 8443 is allowed on the ufw firewall.

The last step of server side configuration is to enable Icecast on system reboot.

systemctl enable icecast2

Setting Up the Source Client

This section will demonstrate how to use Broadcast Using this Tool (BUTT) or Liquidsoap as source clients. These source clients can be used to stream directly from Line input, or to stream from an audio file. BUTT offers a graphical interface, while Liquidsoap has a scripting language and is launched from the command line. You can use either of them as your source client.

Option 1: Broadcast Using this Tool (BUTT)

1. Download and install BUTT (varies based on OS of choice).
2. Launch BUTT and go to "Settings".
3. Add a server with your Icecast server details.

4. Navigate to the "Audio" tab to configure your input device and streaming codec.

5. Go back to the "Main" tab and hit the "Save" button.
6. Click the play button in BUTT's main window. You should see that BUTT has successfully connected to your Icecast server.
7. Visit https://your-ip-or-domain:8443/stream.mp3. You should now be able to listen to the audio stream sent by BUTT on the Icecast mountpoint.

Option 2: Liquidsoap

1. Download and setup Liquidsoap (varies based on OS of choice).
2. Create a liq file which will contain our Liquidsoap configuration.
3. Copy the code snippet below to your liq file. Set host to your domain name or IP address, and password to your source password configured in Icecast server.

set("log.stdout",true)
set("log.file",false)

# Input from default audio port
s = input.portaudio()

# An icecast output in mp3 format
output.icecast(%mp3(bitrate=192),
              host="talesofcode.com", port = 8443,
			  password = "source-password-here",
              fallible=true,
              mount="stream.mp3",
              s)

4. Start Liquidsoap from the command line, passing the liq file as input.

liquidsoap file.liq

5. You should see that Liquidsoap has successfully connected to your Icecast server.
6. Visit https://your-ip-or-domain:8443/stream.mp3. You should now be able to listen to the audio stream from your source client on the Icecast mountpoint.

Liquidsoap is a very powerful open source tool. Refer to its documentation for advanced examples and use cases.