Satellites plugin

From Stellarium Wiki
(Difference between revisions)
Jump to: navigation, search
(Description)
(Current format)
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==Description==
+
{{obsolete|12 November 2011 (but the problem dates from before that)}}
 +
The Satellites plugin simulates artificial satellites in Earth orbit.  Satellite orbits could not be predicted precisely enough using Stellarium's existing orbital models for Solar System bodies, as there are other factor involved - irregularities in the Earth's gravitational field, lunar interactions, atmospheric drag and so on. So this plugin implements the SGP4 and SDP4 orbital models, using as its input data in NORAD's {{wikipedia-en|two-line element set}} (TLE) format. Lists with TLEs for hundreds of satellites are available online and are regularly updated. The plugin downloads the lists prepared by [http://celestrak.com/ celestrak.com] to keep itself up-to-date, but the users can specify other sources online or load updates from local files.
  
The Satellites plugin simulates satellites in Earth orbit. Satellite orbits are not very precisely predicted using the existing orbital models for the planets, as there are other factor involved - irregularities in the Earth's gravitational field, lunar interactions, atmospheric drag and so on.   
+
==Enabling the Satellites plugin==
 +
This plugin comes bundled with Stellarium version 0.10.3, although it is not enabled by default.  To enable the plugin, open the configuration dialog and go to the plugins tab.  Click '''Satellites''' from the list of available plugins and check the '''load at startup''' checkboxYou will need to re-start Stellarium for changes to take effect.
  
This plugin implements the SGP4 and SDP4 models, and takes as it's input data NORAD TLEs (two line elements)TLEs for hundreds of satellites are available online and are regularly updated.  
+
==Using the Satellites plugin==
 +
To see the position of artificial satellites, you must have the observer location set to EarthYou must also turn on Satellite indicators on the main tool bar as shown in the image below:
 +
<div align="center">
 +
http://stellarium.org/wikiimg/sat_howto_02.jpg
 +
</div>
  
http://porpoisehead.net/images/plugin-satellites.jpg
+
===Searching for satellites===
 +
It should now be possible to search for artificial satellites using the regular search dialog (F3).  Note that at any given time, most Satellites will be below the horizon.
 +
<div align="center">
 +
http://stellarium.org/wikiimg/sat_howto_03.jpg
 +
</div>
 +
===Displaying satellite data===
 +
{{obsolete-section}}
 +
<div style="float:right">http://stellarium.org/wikiimg/sat_howto_04.jpg</div>
 +
When you have selected a Satellite, information about it will be shown just as for any other object which is selected.  This includes:
  
==Using the Satellites plugin==
+
* Normal '''positional data''' (RA/Dec, Alt/Azi and so on)
Note that this plugin is still in the early stages of development, and may change quite a lot in the near futureThis description apples to version 0.1.1 of the plugin.
+
* '''Range''' in kilometers.  This is the line-of-sight distance between the observer and the selected satellite
 +
* '''Range Rate''' in kilometers per second.  This is the closing/parting speed of the satellite.  It is useful when calculating doppler shift necessary for communications (and is also just nice to know)
 +
* '''Altitude''' of the satellite above the ground in kilometers
 +
* '''Comms''' data.  Some satellites broadcast on frequencies which can be received by the general public or used by amateur radio operators.  Where such data is known about a satellite Stellarium will show it.
 +
 
 +
<br clear="all"/>
 +
 
 +
===Configuration===
 +
When the satellites plugin is loaded, the configuration button in the plugins tab of the configuration dialog will be enabled.  Clicking this button (or pressing Control+Shift+Z) will open the configuration dialog for the satellites plugin.
 +
 
 +
====Settings tab====
 +
<div style="float:right">http://stellarium.org/wikiimg/sat_howto_05.jpg</div>
 +
In the settings tab you can control how often the Satellites plugin downloads updates for the TLE sets of known satellites.  The default is every 72 hours.  If an update is due when Stellarium is started, it will commence 30 seconds or so after the plugin is loaded.
 +
 
 +
If the box enabling updates from online sources is unchecked, a new button will appear. It allows loading satellite data from local files, a feature useful for computers without Internet access.
 +
 
 +
TODO
 +
- update screenshot
 +
- add information on satellite trajectories
 +
 
 +
<br clear="all"/>
 +
 
 +
====Satellites tab====
 +
<div style="float:right">http://stellarium.org/wikiimg/sat_howto_06.jpg</div>
 +
The Satellites tab shows data on known satellites and lets you choose which ones are displayed.  Note that for each satellite which is displayed, Stellarium must do extra work to calculate and show the position of the satellite.  If Stellarium is running very slowly with the Satellites plugin enabled, try reducing the number of satellites which are displayed.
 +
 
 +
You can select and go to a satellite by double clicking it in the list.
 +
 
 +
At time of writing, this dialog is only doe display information about satellites and changing their visibility.  In future it will be possible to edit descriptions, comms data and so on, but this is not yet implements.
 +
 
 +
TODO
 +
- update screenshot
 +
- add information on selecting satellite groups
 +
- add information on adding/removing satellites
 +
 
 +
<br clear="all"/>
 +
 
 +
====Sources tab====
 +
<div style="float:right">http://stellarium.org/wikiimg/sat_howto_07.jpg</div>
 +
The Sources tab lets you see (and modify) where Stellarium is getting its TLE data from.  The default is a list of sources from [http://celestrak.com celestrak.com].
 +
 
 +
TODO:
 +
- update screenshot
 +
- descriptions of the different files
 +
 
 +
<br clear="all"/>
 +
 
 +
==Adding new satellites==
 +
 
 +
In version 0.7.1 of the plug-in, included with Stellarium 0.11.2, there is a simple way of adding satellites through a window opened by the "+" button on the "Satellites" tab of the plug-in's configuration window. For earlier versions and for more complex tasks (adding/modifying groups, colors, etc.), the only way to do it is by manually editing the satellites list (see below).
 +
 
 +
TODO:
 +
- add screenshot
 +
- explain that it uses the update lists
 +
- explain how to use offline
 +
 
 +
==Editing the satellite list==
 +
 
 +
You can modify the <tt>satellites.json</tt> file manually using a text editor. '''If you are using Windows, it is strongly recommended to use an advanced text editor such as [http://notepad-plus-plus.org/ Notepad++]''' to avoid problems with end-of-line characters. (It will also color the JSON code and make it easier to read.)
 +
 
 +
'''Warning:''' Before editing your <tt>satellites.json</tt>, make a backup copy.  Leaving out the smallest detail (such as a comma or forgetting to close a curly bracket) will prevent Stellarium from starting.
 +
 
 +
The path to the directory which contains <tt>satellites.json</tt> is something like:
 +
{{user data directory|modules\Satellites|modules/Satellites}}
 +
 
 +
Note that the format of the <tt>satellites.json</tt> is different between Stellarium 0.11.2 and previous versions, so be careful.
 +
 
 +
===Current format===
 +
:''Used in Satellites plug-in 0.7.1 and later (Stellarium 0.11.2 and later)''
 +
To add a new satellite, open a new line after line 5 and paste the following, note commas and brackets, they are important:
 +
 
 +
<pre>
 +
"NORAD number":
 +
{
 +
"name": "name of the satellite"
 +
"description": "description goes here",
 +
"comms": [
 +
  {
 +
"description": "downlink 1",
 +
"frequency": 437.49,
 +
"modulation": "AFSK 1200 bps"
 +
  },
 +
  {
 +
"description": "downlink 2",
 +
"frequency": 145.825
 +
  }
 +
                        ],
 +
"groups": ["group1", "group2"],
 +
"tle1": "1 12345U 90005D  09080.85236265 .00000014  00000-0  20602-4 0  5632",
 +
"tle2": "2 12345 98.2700  53.2702 0011918  71.1776 289.0705 14.31818920  653",
 +
"visible": true
 +
},
 +
</pre>
 +
 
 +
Explanation of the fields:
 +
* NORAD number - required parameter, surrounded by double quotes ("), followed by a colon (:). It is used internally to identify the satellite. You should replace the text "NORAD number" with the first number on both lines of the TLE set (in this case, "'''12345'''") It must match the number of the satellite in the source you are adding from if you want the TLE to be automatically updated.
 +
 
 +
The remaining parameters should be listed between two curly brackets and the closing curly bracket must be followed by a comma to separate it from the next satellite in the list:
 +
* name - required parameter. It will be displayed on the screen and used when searching for the satellite with the Find window. Use the description field for a more readable name if you like. (The description field can accept HTML tags such as <tt><nowiki><br/></nowiki></tt> (new line), <code><nowiki><b></b></nowiki></code> (bold), etc.)
 +
* description - optional parameter, double quoted.  Appears when you click on the satellite
 +
* comms- ''optional parameter'', square bracketed list of curly bracketed communications information.
 +
* groups - ''optional parameter'', comma separated list of double quoted group names contained in square brackets.  Used for grouping satellites in the drop down box on the config (see above)
 +
* tle1 - required parameter, line 1 of the TLE, must be contained in double quotes and begin with "1 "
 +
* tle2 - required parameter, line 2 of the TLE, must be contained in double quotes and begin with "2 "
 +
* visible - required parameter, set to true if you want to see it, this can be toggled from the configuration window once the satellite is loaded.
 +
 
 +
You can edit the tags for a satellite, modify the description and comms data, and even add new satellites.
 +
 
 +
===Old format===
 +
Before version 0.7.* of the plug-in (before Stellarium 0.11.2), the format of the <tt>satellites.json</tt> file was slightly different. It used only the name to identify satellites instead of their NORAD number:
 +
<PRE>
 +
"satellite name":
 +
{
 +
"description": "description goes here",
 +
"comms": [
 +
  {
 +
"description": "downlink 1",
 +
"frequency": 437.49,
 +
"modulation": "AFSK 1200 bps"
 +
  },
 +
  {
 +
"description": "downlink 2",
 +
"frequency": 145.825
 +
  }
 +
                        ],
 +
"groups": ["group1", "group2"],
 +
"tle1": "1 12345U 90005D  09080.85236265  .00000014  00000-0  20602-4 0  5632",
 +
"tle2": "2 12345 98.2700  53.2702 0011918  71.1776 289.0705 14.31818920  653",
 +
"visible": true
 +
},
 +
</PRE>
 +
* satellite name - required parameter, double quoted with a colon following.  Use the name as it appears in source you are updating from if you want the TLE to be automatically updated.  Use the description field for a more readable name if you like. (The description field can accept HTML tags such as <tt><nowiki><br/></nowiki></tt> (new line), <code><nowiki><b></b></nowiki></code> (bold), etc.)
 +
 
 +
The remaining parameters should be includes in curly brackets, the closing curly bracket must be followed by a comma to separate it from the next satellite in the list.:
 +
* description - optional parameter, double quoted.  Appears when you click on the satellite
 +
* comms- ''optional parameter'', square bracketed list of curly bracketed communications information.
 +
* groups - ''optional parameter'', comma separated list of double quoted group names contained in square brackets.  Used for grouping satellites in the drop down box on the config (see above)
 +
* tle1 - required parameter, line 1 of the TLE, must be contained in double quotes and begin with "1 "
 +
* tle2 - required parameter, line 2 of the TLE, must be contained in double quotes and begin with "2 "
 +
* visible - required parameter, set to true if you want to see it, this can be toggled from the config once loaded.
 +
 
 +
===Online list creator===
 +
 
 +
A user (LCoronelP) has written a satellites.json creator in PHP using the TLE sources in your config.ini, you can use it [http://www.lbcoders.com/stellarium/createsatjson.php here], and the sourcecode is [http://www.lbcoders.com/stellarium/createsatjson.phps here].
  
TODO
+
Note: This generator only works if your sources are OK.
  
==How you can help==
+
==Sources for TLE data==
Some specific things for non-programmers:
+
*Create a really complete module.ini file. 
+
**All the amateur satellites should have all their comms channels listed for all active satellites.  Also include modulation information, which is currently missing for most spacecraft.
+
**All scientific craft should be added
+
**Please no military spacecraft
+
*Find a list of URLs which link to TLE data for all satellites in the new module.ini file.  Please verify that the owners of the sites are OK with re-distribution of their data under open source licenses.
+
*Someone draw a nice icon for the left menu (for a GUI dialog).
+
*Suggestions and so on.
+
  
For development tasks, see the TODO list, which is maintained in the [http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk/extmodules/Satellites/README?view=markup README] file for the plugin. If you are able to help with any item in this list, please contact the Stellarium developer team via the stellarium-pubdevel mailing list.
+
* [http://celestrak.com/NORAD/elements/ Celestrak], used as default update source, it also has TLE lists beyond those included by default in Satellite plug-in
 +
* [http://www.tle.info/joomla/index.php TLE.info]
 +
* [http://www.space-track.org Space Track], the definitive source, requires signup, operated by United States Department of Defense
  
We also welcome bug reports, feature requests and feedback through the usual channels (trackers, forums and so on).
+
==TODO==
 +
* Provide download links for alternative satellites.json files which include specialist lists of satellites.
  
 
[[Category:Plugins]]
 
[[Category:Plugins]]

Latest revision as of 11:52, 11 March 2012

Some or all of the information on this page is no longer accurate.

It may be relevant to an older version of Stellarium, or it may not be relevant at all. This page itself should be updated, archived or deleted.

This warning has been here since 12 November 2011 (but the problem dates from before that).

The Satellites plugin simulates artificial satellites in Earth orbit. Satellite orbits could not be predicted precisely enough using Stellarium's existing orbital models for Solar System bodies, as there are other factor involved - irregularities in the Earth's gravitational field, lunar interactions, atmospheric drag and so on. So this plugin implements the SGP4 and SDP4 orbital models, using as its input data in NORAD's two-line element set (TLE) format. Lists with TLEs for hundreds of satellites are available online and are regularly updated. The plugin downloads the lists prepared by celestrak.com to keep itself up-to-date, but the users can specify other sources online or load updates from local files.

Contents

[edit] Enabling the Satellites plugin

This plugin comes bundled with Stellarium version 0.10.3, although it is not enabled by default. To enable the plugin, open the configuration dialog and go to the plugins tab. Click Satellites from the list of available plugins and check the load at startup checkbox. You will need to re-start Stellarium for changes to take effect.

[edit] Using the Satellites plugin

To see the position of artificial satellites, you must have the observer location set to Earth. You must also turn on Satellite indicators on the main tool bar as shown in the image below:

sat_howto_02.jpg

[edit] Searching for satellites

It should now be possible to search for artificial satellites using the regular search dialog (F3). Note that at any given time, most Satellites will be below the horizon.

sat_howto_03.jpg

[edit] Displaying satellite data

Some or all of the information in this section is no longer accurate. It may be relevant to an older version of Stellarium.

This warning has been here since some undetermined moment.

sat_howto_04.jpg

When you have selected a Satellite, information about it will be shown just as for any other object which is selected. This includes:

  • Normal positional data (RA/Dec, Alt/Azi and so on)
  • Range in kilometers. This is the line-of-sight distance between the observer and the selected satellite
  • Range Rate in kilometers per second. This is the closing/parting speed of the satellite. It is useful when calculating doppler shift necessary for communications (and is also just nice to know)
  • Altitude of the satellite above the ground in kilometers
  • Comms data. Some satellites broadcast on frequencies which can be received by the general public or used by amateur radio operators. Where such data is known about a satellite Stellarium will show it.


[edit] Configuration

When the satellites plugin is loaded, the configuration button in the plugins tab of the configuration dialog will be enabled. Clicking this button (or pressing Control+Shift+Z) will open the configuration dialog for the satellites plugin.

[edit] Settings tab

sat_howto_05.jpg

In the settings tab you can control how often the Satellites plugin downloads updates for the TLE sets of known satellites. The default is every 72 hours. If an update is due when Stellarium is started, it will commence 30 seconds or so after the plugin is loaded.

If the box enabling updates from online sources is unchecked, a new button will appear. It allows loading satellite data from local files, a feature useful for computers without Internet access.

TODO
- update screenshot
- add information on satellite trajectories


[edit] Satellites tab

sat_howto_06.jpg

The Satellites tab shows data on known satellites and lets you choose which ones are displayed. Note that for each satellite which is displayed, Stellarium must do extra work to calculate and show the position of the satellite. If Stellarium is running very slowly with the Satellites plugin enabled, try reducing the number of satellites which are displayed.

You can select and go to a satellite by double clicking it in the list.

At time of writing, this dialog is only doe display information about satellites and changing their visibility. In future it will be possible to edit descriptions, comms data and so on, but this is not yet implements.

TODO
- update screenshot
- add information on selecting satellite groups
- add information on adding/removing satellites


[edit] Sources tab

sat_howto_07.jpg

The Sources tab lets you see (and modify) where Stellarium is getting its TLE data from. The default is a list of sources from celestrak.com.

TODO:
- update screenshot
- descriptions of the different files


[edit] Adding new satellites

In version 0.7.1 of the plug-in, included with Stellarium 0.11.2, there is a simple way of adding satellites through a window opened by the "+" button on the "Satellites" tab of the plug-in's configuration window. For earlier versions and for more complex tasks (adding/modifying groups, colors, etc.), the only way to do it is by manually editing the satellites list (see below).

TODO:
- add screenshot
- explain that it uses the update lists
- explain how to use offline

[edit] Editing the satellite list

You can modify the satellites.json file manually using a text editor. If you are using Windows, it is strongly recommended to use an advanced text editor such as Notepad++ to avoid problems with end-of-line characters. (It will also color the JSON code and make it easier to read.)

Warning: Before editing your satellites.json, make a backup copy. Leaving out the smallest detail (such as a comma or forgetting to close a curly bracket) will prevent Stellarium from starting.

The path to the directory which contains satellites.json is something like:

  • C:\Users\UserName\AppData\Roaming\Stellarium\modules\Satellites (Windows Vista, Windows 7)
  • C:\Documents and Settings\UserName\Application Data\Stellarium\modules\Satellites (Windows XP)
  • HomeDirectory/Library/Preferences/Stellarium/modules/Satellites (Mac OS X)
  • ~/.stellarium/modules/Satellites (Linux)

(Note that this is a hidden folder, so in order to find it you may need to change your computer's settings to display hidden files and folders.)

Note that the format of the satellites.json is different between Stellarium 0.11.2 and previous versions, so be careful.

[edit] Current format

Used in Satellites plug-in 0.7.1 and later (Stellarium 0.11.2 and later)

To add a new satellite, open a new line after line 5 and paste the following, note commas and brackets, they are important:

		"NORAD number": 
		{
			"name": "name of the satellite"
			"description": "description goes here",
			"comms": [
			   {
				"description": "downlink 1",
				"frequency": 437.49,
				"modulation": "AFSK 1200 bps"
			   },
			   {
				"description": "downlink 2",
				"frequency": 145.825
			   }
                        ],
			"groups": ["group1", "group2"],
			"tle1": "1 12345U 90005D   09080.85236265  .00000014  00000-0  20602-4 0  5632",
			"tle2": "2 12345 98.2700  53.2702 0011918  71.1776 289.0705 14.31818920   653",
			"visible": true
		},

Explanation of the fields:

  • NORAD number - required parameter, surrounded by double quotes ("), followed by a colon (:). It is used internally to identify the satellite. You should replace the text "NORAD number" with the first number on both lines of the TLE set (in this case, "12345") It must match the number of the satellite in the source you are adding from if you want the TLE to be automatically updated.

The remaining parameters should be listed between two curly brackets and the closing curly bracket must be followed by a comma to separate it from the next satellite in the list:

  • name - required parameter. It will be displayed on the screen and used when searching for the satellite with the Find window. Use the description field for a more readable name if you like. (The description field can accept HTML tags such as <br/> (new line), <b></b> (bold), etc.)
  • description - optional parameter, double quoted. Appears when you click on the satellite
  • comms- optional parameter, square bracketed list of curly bracketed communications information.
  • groups - optional parameter, comma separated list of double quoted group names contained in square brackets. Used for grouping satellites in the drop down box on the config (see above)
  • tle1 - required parameter, line 1 of the TLE, must be contained in double quotes and begin with "1 "
  • tle2 - required parameter, line 2 of the TLE, must be contained in double quotes and begin with "2 "
  • visible - required parameter, set to true if you want to see it, this can be toggled from the configuration window once the satellite is loaded.

You can edit the tags for a satellite, modify the description and comms data, and even add new satellites.

[edit] Old format

Before version 0.7.* of the plug-in (before Stellarium 0.11.2), the format of the satellites.json file was slightly different. It used only the name to identify satellites instead of their NORAD number:

		"satellite name": 
		{
			"description": "description goes here",
			"comms": [
			   {
				"description": "downlink 1",
				"frequency": 437.49,
				"modulation": "AFSK 1200 bps"
			   },
			   {
				"description": "downlink 2",
				"frequency": 145.825
			   }
                        ],
			"groups": ["group1", "group2"],
			"tle1": "1 12345U 90005D   09080.85236265  .00000014  00000-0  20602-4 0  5632",
			"tle2": "2 12345 98.2700  53.2702 0011918  71.1776 289.0705 14.31818920   653",
			"visible": true
		},
  • satellite name - required parameter, double quoted with a colon following. Use the name as it appears in source you are updating from if you want the TLE to be automatically updated. Use the description field for a more readable name if you like. (The description field can accept HTML tags such as <br/> (new line), <b></b> (bold), etc.)

The remaining parameters should be includes in curly brackets, the closing curly bracket must be followed by a comma to separate it from the next satellite in the list.:

  • description - optional parameter, double quoted. Appears when you click on the satellite
  • comms- optional parameter, square bracketed list of curly bracketed communications information.
  • groups - optional parameter, comma separated list of double quoted group names contained in square brackets. Used for grouping satellites in the drop down box on the config (see above)
  • tle1 - required parameter, line 1 of the TLE, must be contained in double quotes and begin with "1 "
  • tle2 - required parameter, line 2 of the TLE, must be contained in double quotes and begin with "2 "
  • visible - required parameter, set to true if you want to see it, this can be toggled from the config once loaded.

[edit] Online list creator

A user (LCoronelP) has written a satellites.json creator in PHP using the TLE sources in your config.ini, you can use it here, and the sourcecode is here.

Note: This generator only works if your sources are OK.

[edit] Sources for TLE data

  • Celestrak, used as default update source, it also has TLE lists beyond those included by default in Satellite plug-in
  • TLE.info
  • Space Track, the definitive source, requires signup, operated by United States Department of Defense

[edit] TODO

  • Provide download links for alternative satellites.json files which include specialist lists of satellites.
Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox