Simple ISS Notification System





Introduction: Simple ISS Notification System

Epilog Challenge 9

This is an entry in the
Epilog Challenge 9

What is the International Space Station and Why do you want to predict where it is?

To answer the first question we can look at the NASA website for an answer. Which in short is:

The International Space Station is a large spacecraft. It orbits around Earth. It is a home where astronauts live.
The space station is also a science lab. Many countries worked together to build it. They also work together to use it.The space station is made of many pieces. The pieces were put together in space by astronauts. The space station's orbit is about 220 miles above Earth. NASA uses the station to learn about living and working in space. These lessons will help NASA explore space.

The second question is a little harder to answer - But I'll try.

I am a Amateur Radio Operator (or Ham Radio Operator) - one thing that I've always found fun was to use a low powered hand held (5 watt or less) radio and communicate with orbiting satellites. The ISS has radio equipment on board.

Early in my ham days I use to communicate with the satellites quite a bit, even making some contacts with just the rubber ducky antenna - something very hard to do. I made a few contacts with the ISS using APRS (automatic packet reporting system) That was in 2013 - a long while ago, I've been very inactive since then. It's something I've wanted to get back into thou.

In 2013 I wrote a couple of PHP scripts for the command line that would tell me the location of the ISS, and help to predict when it would be over head. At that time I used a blink stick, and had it change colors as the ISS approached. Thanks to the work at and his API it was pretty easy to make these.

2018 - 5 years later I finally converted these PHP to Arduino C (actually it was very easy to do.)

My project uses a D-Duino (which is really a NodeMCU with a OLED on board), that is all there is to it.

I am still using the same API from

I've also wrote some code to use a D1 Mini and a WS2812 Shield (see my Supervisor Eric Project for more on that).

Step 1: Simple Hardware.

D-Duino (NodeMCU)

That is it, that is all that is required. OF course you can use other hardware - this should work on any ESP8266 device that can use a I2C OLED. The D-Duino is for the most part a NodeMCU with the addition of the OLED.

The code can be found

You will need to have the ESP8266 boards installed in the Arduino IDE. Instructions can be found here:

(the easiest way is with the boards manager)

You will also need some libraries - I think all of these can be found in the library manager now (but I'm not 100% sure about that).

Libraries Needed:





(I'm not sure where I got TImeLib from, and it maybe included in with Arduino IDE ??)

The simplest way to install these is using the library manager. If not follow the instructions with each library.

Step 2: The Sketches

There currently two sketches and three PHP scripts included in the github repository.

DDuino_ISS_notification which should be used with the D-Duino hardware from above.

And EricISSnotification which uses my previous "Supervisor Eric" from the show "People of Earth" project. (More on this later)

In both sketches near line 30 (or somewhere really close to it) - You'll see a couple of float variables called mylat and mylon. You will need to change these two lines with your Latitude and Longitude - if you don't know your Lat and Lon you can use this website The center of your town should be fine. It doesn't have to match your excacted latitude or longitude. The sketches do some rounding, and other maths to come up with an approximate distance the ISS in U.S. Miles.

I believe this is the only thing that needs to be changed in the sketches.

The maths for the distance calculation are based on the great-circle distance between two points, and the formal can be found here -

This site provides a lot of information about how to calculate distance between two latitudes and longitudes as well as bearing. We aren't using any bearing calculations for this.

For the formal to work we do need to get a theta and convert some degree to radiant, and the other way around, radiant to degree. Since the Arduino doesn't do math so well, we have to help it out a little with the conversions.

void getDistance() {

float theta, dist, miles;

theta = mylon - isslon;

dist = sin(deg2rad(mylat)) * sin(deg2rad(isslat)) + cos(deg2rad(mylat)) * cos(deg2rad(isslat)) * cos(deg2rad(theta));

dist = acos(dist); dist = rad2deg(dist);

miles = dist * 60 * 1.1515;

distance = miles;


float deg2rad(float n) {

float radian = (n * 71)/4068;

return radian;


float rad2deg(float n) {

float degree = (n*4068)/71;

return degree;


The bulk of the maths is done near line 127 - IF you would like a different distance (say KM or Nautical Miles)

you can change the "miles = dist * 60 * 1.1515;" line.

For KM it would be something like "miles = (dist*60*1.1515) * 1.609344;"

For Nautical Miles something like "miles = (dist*60*1.1515)*0.8684;"

You'll probably also want to change the Serial print line and the OLED display line that say miles to your new measurement.

Which is line 86 and 96 in the DDuino_ISS_notification sketch.

Step 3: The Eric Sketch

Supervisor Eric is an AI or alien from the TBS TV People of Earth, Please see my other Instructable on my build.

The very basic you need for this notification system thou is a D1 Mini and the WS2812 shield - having it in a nice box with a nice lens makes it look - well nice.

Once again, any ESP8266 with a WS2812 pixel should work, there really is no magic going on here - The WS2812 shield is connected to D2 on the D1 mini (which I believe is pin 4 on NodeMCU boards, and maybe other ESP8266 boards).

To the sketch:

As above you'll need to change your latitude and longitude in the sketch near line 27. And like above this sketch also calculates a distance between to latitude and longitudes. Unlike the above sketch, this only display is with the WS2812 Neopixel LED.

The maths are near line 96, but otherwise are the same as above. There is still serial output if you wish to see what is going on. This Sketch only does ISS location and distance calculations - it doesn't do the pass predictions or how many people are in space.

* It should be noted that the distance here is in Miles, it can be changed if you like, but you'll need to make a few more changes for your units. *

Near Line 116:

void setColor() {

if (distance <= 1350 && distance >=1201) {colorDisplay(strip.Color(255,0,0),p);}

if (distance <=1200 && distance >=1151) {colorDisplay(strip.Color(255,153,0),p);} //looks more yellow to me

if (distance <=1150 && distance >= 951) {colorDisplay(strip.Color(255,255,0),p);} //looks green/yellow to me

if (distance <=950) {colorDisplay(strip.Color(0, 255, 0), p);}

if (distance >= 1351) {colorDisplay(strip.Color(0,0,0),p);}


The units are in miles, and if you need to change to KM or NM you'll also want to change these lines.

What is going on here thou, At 1350 miles, the ISS is just on the horizon and you can just start to hear the transponders from the radio - it's not great, and communication at this point can't really happen. The LED turns RED - this is a heads up - the ISS is getting close.

After a short time, or if the ISS is between 1150 and 1200 miles, the LED will turn orange - this really look more yellow to but it is support to be orange. - At 1150 miles you should start to hear quite a bit more - two way communication will probably still not be possible on a 5 watt HT.

Between 950 and 1150 miles - The LED should turn yellow - you have a decent chance of making a contact - still not great, but it is at least possible at this point (Yellow looks more green to me than yellow - so something else to work on)

Under 950 miles the LED will be a solid GREEN - and two way contacts can be made.

As the ISS moves away from the LED will go from Green to Yellow to Orange to Red and then finally to OFF.

It should be noted here, this all happens very quickly - most passes in my area last under 10 mins, and normal usable contact time is under 5 mins.

It should also be noted that the ISS can change it's location, and that the API may or may not be update - so even if you have a green light - you might not hear anything.

** Running the amateur equipment is done optional and voluntary as well, and while they try to run the equipment there are time when they have to shut it down for power, or because of what they need to do. It's always a good idea to check AMsat or ARISS websites **

Step 4: The PHP Code

In the github repository, I've included my PHP code from 2013.

The code was designed to run from the CLI (or Command line). It's been awhile since I wrote these but I think the only requirement was to have the JSON extensions enabled.

The scripts still work, and if you'd like to run them feel free to do so!

For Windows Users there is information here on installing PHP

Be sure to install the CLI version. I think as you install you can select which extensions to turn on.

Linux users depend on your distro - I use an Ubuntu based distro - and synaptic as my package manager.

You'll want php7.0-common, php7.0-json, php7.0-cli, php7.0-curl

I don't think I used CURL with these, so you may not need that one. The rest should be found in your package manger of choice or on the website.

Two of the scripts will need to be edited with your latitude and longitude - they are not very long, and what needs to be changed is right at the top of the script. They are iss-location.php and iss-pass-api.php

iss-location.php has my old blink stick calls left in it - I'm not sure those work any more - but you can see I was changing the LED in much the same way I do with my "Eric Notification". I don't think they are causing any problems, but you may want to comment them out.

iss-pass-api.php uses the epoch time and give a local time of the predicted passes. In all honesty I prefer the PHP version of this script when compared to the DDuino version (which right now only does UTC predictions)

The PHP version is also formated nicer for display - but that is really a minor thing.

The final PHP script is iss-people.php - and it will display the names and which space craft they are on. That is all it does. (And this information doesn't change often)

The basics of running a PHP script from the command line are:

$ php iss-people.php

PHP files are text files, and can be opened by any text editor. Windows users I think that I saved these so they have both line and carriage returns. IF not might work for them.

Step 5: The Videos and More ISS & Ham Information

Getting a Ham License In the United State:

Not in the U.S.? Each country has there own set of rules and license guides - check with who governs your communications (Here in the U.S. that's the FCC Federal Communications Commision)

Calculate distance, bearing and more between latitude and longitude points.

This would have been a whole lot harder to make with out the very useful APIs from Open Notify

How to see the Space Station from the Ground.

AMSAT Radio Amateur Satellite

AMSAT Information on Radio on the ISS

ARISS Amateur Radio on the International Space Station

ISS Fan Club - ISS Frequencies

Wikipedia Entry on APRS

Step 6: Final Thoughts...

This was a fun project, with very simple hardware.

There are a couple of things I'd like to change, but overall I'm very happy with the results.

Things that need to be changed:

1) Figure out a way to have pass predictions in local time, not UTC

2) Find better color code numbers for orange and yellow.

3) Update to work with the ESP32 X-board, with OLED and 4 Neopixels.

If you find this or any of my projects useful or enjoyable please support me.

Anything I do get goes to buy more parts and make more/better projects.



  • Epilog Challenge 9

    Epilog Challenge 9
  • Sew Warm Contest 2018

    Sew Warm Contest 2018
  • Paper Contest 2018

    Paper Contest 2018

We have a be nice policy.
Please be positive and constructive.