This repository contains the development sources of the GNU Radio-based receiver for the Blockstream Satellite network.
In order to set up your receiver system, please read the following information carefully. For additional help, go to the #blockstream-satellite IRC channel on freenode.
IMPORTANT: Please note that the Blockstream Satellite network was updated
with backwards incompatible changes on March 11, 2019. From this date on, the
required Blockstream Satellite receiver version should be greater than or equal
to v1.3.0. The most recent version is v1.4.0, which is the recommended one.
Meanwhile, Bitcoin FIBRE should be the version from the master
branch.
During your initial set-up, you will need to go through the following steps:
- Check your coverage at Blockstream's Interactive Coverage Map.
- Get the required hardware - software defined radio (SDR) interface, satellite dish/antenna, low-noise block downconverter (LNB), power supply, mounting hardware, cables and connectors.
- Install the required software - Bitcoin FIBRE, GNU Radio and GR OsmoSDR.
- Install the satellite receiver.
- Align your satellite dish with the help of the receiver application.
All of these steps are thoroughly explained next.
- Hardware Requirements
- Software Installation
- Antenna Pointing
- Run the Receiver
- Run Bitcoin FIBRE
- Satellite API
- Running on Raspberry Pi
- Frequent issues and questions
To utilize the Blockstream Satellite network, you must have the following hardware at a minimum:
- Satellite dish (antenna)
- LNB (linear polarization w/ LO stability <= 200 kHz)
- LNB power supply
- LNB mounting bracket
- Software Defined Radio (SDR) interface
- Cables, connectors, and mounting hardware
These items are available from resellers around the world and we are currently working with a vendor to provide complete kits and components.
Blockstream Satellite is designed to work with small antennas. In Ku band, it is expected to work with antennas of only 45cm in diameter, while in C band it is expected to work with 60cm or higher. However, a larger antenna is always better. When possible, we recommend installing an antenna larger than the referred minimum if one is readily available. 60cm, 90cm, and 1.2m antennas are readily available.
Other than size, the only additional requirement is that the antenna will work with the frequency band that suits your coverage region.
Blockstream Satellite operates in Ku high band, Ku low band and C band, depending on region. Ku high band is used in North America and South America. Ku low band is used in Africa and Europe. C band is used in Asia-Pacific region.
C band: 3.7 GHZ - 4.2 GHz
Ku low band: 10.7 to 11.7 GHz
Ku high band: 11.7 to 12.75 GHz
You can always use antennas designed for higher frequencies. For example, an antenna designed for Ka band will work for Ku bands and C band, as it is designed for higher frequencies than the ones used by Blockstream Satellite. However, a C band antenna will not work for Ku bands, as it is designed for lower frequencies.
The following table summarizes the transmission bands of the satellites we use:
| Satellite | Band |
|---|---|
| Galaxy 18 | Ku High |
| Eutelsat 113 | Ku High |
| Telstar 11N Africa | Ku Low |
| Telstar 11N Europe | Ku Low |
| Telstar 18V | C |
There are 3 parameters of an LNB that must be met in order to use Blockstream Satellite:
First, you must verify that the input frequency range of the LNB encompasses the frequency of the Blockstream Satellite signal in your coverage area. For example, if you are located in North America and you are covered by the Galaxy 18 satellite, your Blockstream Satellite frequency is 12.02285 GHz. Thus, an LNB that operates from 11.7 GHz to 12.2 GHz would work. In contrast, an LNB that operates from 10.7 GHz to 11.7 GHz would NOT work.
Note on “Universal” LNB:
A Universal LNB, also known as Universal Ku band LNB, is an LNB that supports both "Ku low" and "Ku high" bands. We recommend using this type of LNB only within Ku low band region, that is, within coverage of either Telstar 11N Africa or Telstar 11N Europe.
The rationale is that a 22 kHz tone must be sent to the Universal LNB in order to switch its sub-band. However, since the setup described in this guide is receiver-only, it is not able to generate the 22 kHz tone by itself. Now, because the default Ku sub-band of Universal LNBs is typically the low band, it is often acceptable to use these within Ku low band region, as the 22 kHz tone generator won't be necessary.
In case you do want to switch the sub-band of an Universal LNB in order to use it within Ku high band region, you will need to place a 22 kHz tone generator inline between the LNB and the power inserter. This is because the tone generator uses power from the inserter while delivering the tone directly to the LNB.
Such tone generators can be found in the market as pure generators. Alternatively, you can get a "satellite finder" device that embeds a 22 kHz generator internally. If choosing the latter, it is important to note that the satellite finder must be one that can be used inline between the power supply and LNB, namely one with signal input (from LNB) and output (towards power inserter), i.e. with two connectors. Some finders have just a single connector as they are not intended to be used inline.
Blockstream Satellite requires an LNB with Linear Polarization. While most Ku band LNBs are linearly polarized, some popular satellite TV services use circular polarization. A circularly polarized LNB will NOT work with Blockstream Satellite.
If an LNB is described to feature horizontal or vertical polarization, then it is linear. In contrast, if an LNB is described as Right Hand or Left Hand Circular Polarized (RHCP or LHCP), then it is circular and will NOT work with Blockstream Satellite.
Most LNBs will have a local oscillator (LO) stability parameter referred to as
“LO stability”, or metrics such as "LO accuracy" and "LO drift". These are
normally specified in +/- XX Hz, kHz or MHz. A stability specification of <= +/- 200 kHz is preferable for better performance. However, if you would like
(or you need) to use a less stable LNB, it can also be used. The difference is
that, in this case, you will need to run the system in Scan Mode, as
described in Frequency Scan Mode.
An LNB that relies on a phase-locked loop (PLL) frequency reference is typically more accurate and stable. Hence, we advise to look for a PLL LNB, instead of a traditional dielectric oscillator (DRO) LNB.
Note on LNBF:
The feedhorn is the horn antenna that attaches to the LNB. It collects the signals reflected by the satellite dish and feeds them into the LNB, towards the receiver. The acronym LNBF stands for "LNB with feedhorn" and refers to the LNB that already contains an integrated feedhorn. This is the most typical nowadays and, for this reason, almost always the term LNB already refers to a LNBF implicitly. To avoid confusion, we advise to look for an LNBF.
In Summary:
You are advised to use a PLL LNBF with linear polarization and LO stability
ideally within +- 200 kHz or less. The LNB should be suitable for the
frequency of the satellite covering your location. Also, to avoid the need of a
tone generator, Universal LNBs are not recommended within Ku high band region.
Most LNBs require anywhere from 13 VDC to 30 VDC to be injected on its coaxial port. For TV receivers, it is normally the receiver that provides power to the LNB directly via the coaxial cable, so you wouldn't see an external power supply in such setups. However, there are systems that rely on external power injectors and, for this reason, these can be found easily in the market.
One particular technology that requires a power supply is the one known as "Single Wire Multiswitch" (SWM). You can look for an SWM power inserter and use it in your setup.
Just be sure to check the power/voltage requirement of your LNB and ensure that your power injector matches. Also, note that some LNBs known as "dual polarization LNBs" use the supplied voltage to switch between polarization options. For instance, in the case of dual polarization linear LNB, to switch between horizontal and vertical polarization. Thus, for example, by supplying 13 VDC you have horizontal, while with 18 VDC you have vertical polarization. Please consider this when pointing your antenna if that is your case.
The dish likely comes with a mounting bracket, but you’ll need one designed to accept a generic LNB. Also, it is good to have a bracket that is flexible for rotation of the LNB, so that you can control its "skew". Although all mounting brackets do allow rotation, some can be limited in the rotation range.
Such mounting brackets attach to the feed arm of the antenna and have a circular ring that will accept a generic LNB.
There are many Software Defined Radio (SDR) interfaces in the market today. Blockstream Satellite is currently predominantly used with the RTL-SDR, model RTL2832U & R820T2, which is a low-cost SDR dongle. This is the SDR interface that is mostly supported and the one that we recommend.
We recommend specifically an RTL-SDR dongle that features a temperature-controlled crystal oscillator (TCXO), since this type of oscillator promotes better frequency stability. There are a few models in the market featuring TCXO with frequency accuracy within 0.5 ppm to 1.0 ppm.
IMPORTANT: For users within the coverage of satellite Telstar 11N
Europe, we recommend purchasing an RTL-SDR with extended tuning range. The
reason is that the satellite frequency in this area is such that, when using an
LNB for Ku low band (with 9.75 GHz LO), the RTL-SDR needs to be configured
with a frequency that is too close to the maximum supported frequency of the
RTL-SDR model that is recommended for other regions (with the R820T2 tuner). The
extended range RTL-SDR uses another tuner (the E4000), whose frequency range is
more than sufficient to cover the frequency that is necessary for Telstar 11N
Europe.
In addition to the RTL-SDR, there is also support for USRP SDRs, which is a higher-cost SDR product family from Ettus Research. Besides, any other SDR platform supported by GNU Radio can be used, provided that it is able to receive frequencies within roughly the 1 GHz to 2 GHz range. Note, however, that in this case the Receiver's source code must be modified to include the given SDR interface.
You’ll need to connect your SDR to a non-powered port on the LNB power supply. The powered port of the power supply, in turn, will be connected to the LNB. You’ll need to ensure that you have the necessary coaxial cables and connectors to make these interfaces. The connections are illustrated below:
Note: Not every RTL-SDR has the same interface connector. Some use the SMA connector and some use MCX. Be sure to order the correct cable and adapters to make the necessary connections.
There are currently binary packages to facilitate the installation in the following distribution/releases:
- Ubuntu bionic (18.04)
- Fedora 28
- CentOS 7*
If using Ubuntu bionic, you can install the packages by running:
add-apt-repository ppa:blockstream/satellite
apt-get update
apt-get install satellite
This should install all dependencies, including GNU Radio and GrOsmoSDR. In case
the add-apt-repository command is not available in your system, you will need
to run apt install software-properties-common.
If using Fedora 28, run:
dnf copr enable blockstream/satellite
dnf install satellite
If the command copr enable is not available, you will need to install
dnf-plugins-core.
Lastly, if using CentOS 7, assuming you have EPEL package installed, run:
yum copr enable blockstream/satellite
yum install satellite
Similarly, if copr enable is not available in your system, you need to install
yum-plugin-copr.
Note that, if you don't have the EPEL package (or another source) installed in
your CentOS 7 system, the above won't find the gnuradio and gr-osmosdr
dependencies and consequently will fail. You can install EPEL using:
yum install epel-release
*Note regarding CentOS 7: at the moment, the binary package for this distribution/release installs solely the console-only receiver applications. It does not install the applications that feature a GUI.
The two main prerequisites to build and install the Blockstream Satellite receiver from source are:
- GNU Radio: http://gnuradio.org (Version 3.7.10 or greater)
- gr-osmosdr: https://github.com/osmocom/gr-osmosdr
When installing these, just make sure to pick suitable versions. Blockstream Satellite works with GNU Radio version 3.7.10 or later.
In case you are flexible with the distribution/release that you can use, we advise using one of the following, where GNU Radio 3.7.11 is available:
- Ubuntu bionic (18.04)
- Fedora 28
- CentOS 7
The following commands attempt to install GNU Radio version 3.7.11, but you can try 3.7.10 or any later version in case 3.7.11 is not available in your system:
Debian/Ubuntu:
apt install gnuradio=3.7.11* gr-osmosdr
Fedora
dnf install gnuradio-3.7.11 gr-osmosdr gnuradio-devel
RHEL/CentOS
yum install gnuradio-3.7.11 gr-osmosdr gnuradio-devel
NOTE 1: For the Fedora/RHEL/CentOS distributions, note that the GNU Radio
development package (gnuradio-devel) package is also needed. It is included in
the above commands.
NOTE 2: In CentOS, you need the EPEL package (or another source) in order to
find the gnuradio and gr-osmosdr packages. You can install it using:
yum install epel-release
Aside from GNU Radio and GrOsmoSDR, you should have make, cmake and
swig. For completeness, install the following packages before proceeding:
Debian/Ubuntu:
apt install make cmake swig pkg-config doxygen graphviz
Fedora
dnf install make cmake swig pkg-config doxygen graphviz gcc-c++ cppunit-devel
RHEL/CentOS
yum install make cmake swig pkg-config doxygen graphviz gcc-c++ cppunit-devel
After installing prerequisites, the next step is to build and install the
building blocks of the Blockstream Satellite receiver, that is, the GNU Radio
Out-of-Tree (OOT) modules named gr-blocksat and gr-framers. To do so, at the
root folder of the satellite repository, run:
$ make framers
$ sudo make install-framers
$ make blocksat
$ sudo make install-blocksat
Before proceeding, ensure that the installed Python packages for framers and blocksat can be found:
python -c "import framers; help(framers)"
python -c "import blocksat; help(blocksat)"
If nothing is displayed, then follow the solution in Import Error (FAQ section). If you are on Fedora or CentOS, you will likely need to include the path as follows:
export PYTHONPATH=/usr/local/lib64/python2.7/site-packages:$PYTHONPATH
Also, to prevent any errors on the next steps, make sure that the shared
libraries from framers and blocksat that were installed above can indeed be
located by your system.
If your are on Ubuntu, you will likely need to run:
ldd /usr/local/lib/python2.7/dist-packages/blocksat/_blocksat_swig.so | grep blocksat
Meanwhile, if you are on Fedora/CentOS, you will probably need to run:
ldd /usr/local/lib64/python2.7/site-packages/blocksat/_blocksat_swig.so | grep blocksat
If the result is not found, then follow the solution in
Segmentation Fault (FAQ section). This
will involve adding a path like /usr/local/lib (on Ubuntu) or
/usr/local/lib64 (on Fedora/CentOS) to the search path of shared libraries,
as follows:
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
# or
export LD_LIBRARY_PATH=/usr/local/lib64:$LD_LIBRARY_PATH
Once the Python packages and the shared libraries are within reach, move on to the next step.
To do so, run:
$ make
$ sudo make install
NOTE: In CentOS, depending on your GNU Radio installation, it is possible that you are only able to build and install the receiver applications that are console-only (without the GUI). This is the case when you see
Block key "qtgui_xxx" not foundduring themakestep.To do so, run:
make GUI=0 sudo make installAlso, on a headless setup, you will need a virtual display server in order to build. You can follow the details on the FAQ section, but in summary you can overcome this by installing
xorg-x11-server-Xvfband running the build/install steps as follows:xvfb-run make GUI=0 sudo make install
-
blocksatorframerscannot be found ("ImportError")Ensure that Python can load modules from the location where
gr-framersandgr-blocksatwere installed. See the information in the FAQ section. -
Block key "blocksat_xxx" not found
The above solution is applicable.
-
Segmentation fault
If running the system on a Red Hat-derived distributions, a quick test is to set the
LD_LIBRARY_PATHenvironment variable to include the/usr/local/lib(or/usr/local/lib64) path. If this is not the case or if this does not solve the segmentation fault, please refer to the debugging information in the FAQ section. -
GNU Radio development package
If you see the error Could not find a package configuration file provided by "Gnuradio" during the
cmakestep of the above build, meaningGnuradioConfig.cmakeorgnuradio-config.cmakefiles were not found, make sure to install thegnuradio-develorgnuradio-devpackage.
Further issues are listed at the FAQ section.
Aligning a satellite antenna is a precise procedure. Remember that the satellites are over 35,000 km (22,000 mi) away. A tenth of a degree of error will miss the satellite by more than 3500 km.
Before mounting your satellite dish, it is important to consider the antenna alignment angles required for your specific location of interest. To obtain these, first use the tool below, available within Blockstream's coverage page:
After entering your address or latitude/longitude, this tool will give you three parameters, azimuth, elevation and polarization angles, explained next.
The azimuth is the side to side adjustment angle of your antenna. If you think of the antenna fixed within a vertical plane and loose such that it can be rotated from side to side, the azimuth determines the direction to which it points after being rotated. 0 degrees refers to North, 90 degrees points to East, 180 degrees to South and 270 degrees to West.
The elevation is the up and down adjustment of your antenna. The antenna aiming tool provides the number of degrees above the horizon to which your antenna must point. 0 degrees represents pointing at the horizon and 90 degrees is pointing straight up.
The polarization parameter is how many degrees your LNB will need to be rotated. Many LNBs will provide a scale of degrees to assist in setting the LNB skew.
Once you have your azimuth, elevation, and polarization, you can identify the general direction your antenna must point. Use a compass or smartphone app to visually check the direction. Ensure that there are no obstacles such as trees or buildings in the path between your antenna location and the area of the sky that your antenna will point. It is important that you have clear line of sight to that area of the sky.
NOTE: There are many useful smartphone apps available for Android and iOS that will aid in pointing your antenna. Some even have augmented reality features that allow you to see the satellite in the sky so that you can ensure you have good line of sight. We advise to use such apps, as they can be quite helpful.
IMPORTANT: If using a compass app on a smartphone, make sure to configure the app such that it displays "true north", instead of the "magnetic north".
Now that you have verified you have clear line of sight, it is time to mount your antenna. Install the satellite antenna according to the directions accompanying it, or have it done professionally.
If you install it yourself, proceed with the following steps:
- Certify that the pole on which the dish is mounted is completely level.
- Set the elevation of the antenna to the parameter provided by the antenna aiming tool (above). Remember this is the up and down angle. Many antennas will have an elevation scale on the back of the dish that you can use to set the approximate elevation.
- Set the LNB polarization to the parameter provided by the antenna aiming tool. This involves rotating the LNB. There is typically a polarization rotation scale on the LNB or the LNB mounting bracket.
To locate the Blockstream Satellite signal and perform fine adjustments to your antenna alignment, you will need:
- Computer connected to an SDR interface and with both GNU Radio and Blockstream Satellite Receiver installed.
- LNB power supply with electricity to power it.
- Coax cable to connect LNB to LNB power supply.
- Cable/adapters to connect the SDR to the LNB power supply. If using an RTL-SDR that has SMA output and a power supply with F female connector in the input (the most typical case), use a cable that has SMA male on one end and F male on the other, or use a normal SMA cable (male on both ends) together with an SMA female to F male adapter.
NOTE: This process is more easily performed with a laptop than can be watched while moving the antenna. If you are not able to have a computer at the antenna site, you’ll need two people: one to move the antenna and one to monitor the laptop.
- With power disconnected from the LNB power supply, connect the SDR to the non-powered port on the LNB power supply.
IMPORTANT: Do NOT connect the powered port of the LNB power supply to the SDR interface. Permanent damage may occur to your SDR and/or your computer.
-
Connect the powered port of the LNB power supply to the LNB using coaxial cable.
-
Turn the LNB power supply on.
NOTE: If using a power injector designed for "Single Wire Multiswitch" (SWM) systems, the ports are typically labeled as follows. The non-powered port is labeled as “Signal to IRD”, which means "signal to integrated receiver/decoder". This is the port that should be connected to the RTL-SDR. The powered port, in turn, is labeled “Signal to SWM”. This is the port that should be connected to the LNB.
You are almost ready to run the receiver. The only missing step is to compute the frequency to be passed as argument to the receiver application.
The frequency parameter depends on the frequency of the satellite covering your location and the frequency of your LNB's local oscillator (LO) frequency, so it is specific to your setup. Also, the computation differs slightly for C band and Ku band.
For Ku band (either high or low), the frequency parameter is computed as follows:
frequency_parameter_ku = satellite_frequency - lnb_lo_frequency
Meanwhile, for C band, it is computed as:
frequency_parameter_c = lnb_lo_frequency - satellite_frequency
To find your satellite's frequency, first go to blockstream.com/satellite and check which one is your satellite (covering your location). Then, find the frequency and the corresponding band of the satellite in the table that follows.
| Satellite | Band | Frequency |
|---|---|---|
| Galaxy 18 | Ku High | 12022.85 MHz |
| Eutelsat 113 | Ku High | 12026.15 MHz |
| Telstar 11N Africa | Ku Low | 11476.75 MHz |
| Telstar 11N Europe | Ku Low | 11504.02 MHz |
| Telstar 18V | C | 4057.5 MHz |
For the LNB's LO frequency, check the product's information. The typical LNB LO frequencies for the bands of interest are summarized below:
| LO Frequency | 5.15 GHz | 9.75 GHz | 10.60 GHz | 10.75 GHz |
|---|---|---|---|---|
| Band | C | Ku Low | Ku High | Ku High |
Now, pick the correct formula for your signal band and compute the parameter. For example, if your LNB has an LO frequency of 10750 MHz and you're connecting to Eutelsat 113 at 12026.15 MHz (Ku high band), the frequency parameter becomes 1,276,150,000 Hz, that is:
1,276,150,000 Hz = 12,026,150,000 Hz - 10,750,000,000 Hz
^ ^ ^
^ ^ ^
frequency_parameter_ku = satellite_frequency - lnb_lo_frequency
NOTE: the blocksat receiver application expects the frequency parameter in Hz.
The following table summarizes the frequencies (in Hz) that are required when launching the blocksat receiver application, considering the typical LNB LO frequencies:
| LO Frequency | 5.15 GHz | 9.75 GHz | 10.60 GHz | 10.75 GHz |
|---|---|---|---|---|
| Galaxy 18 | 1422850000 | 1272850000 | ||
| Eutelsat 113 | 1426150000 | 1276150000 | ||
| Telstar 11N Africa | 1726750000 | |||
| Telstar 11N Europe | 1754020000 | |||
| Telstar 18V | 1092500000 |
The next step is to run the blocksat receiver aplication. At this point, to facilitate the antenna alignment, we recommend using the blocksat receiver in GUI mode. Later on, once the antenna is pointed, you can switch to the lightweight console-only application. To launch the GUI receiver, run:
blocksat-rx-gui -f [freq_in_hz]
where freq_in_hz is the frequency parameter, specified as an integer number
in units of Hz.
Example:
blocksat-rx-gui -f 1276150000
Possible Issues
- Ensure that your
PYTHONPATHenvironment variable is set to the installed location ofgr-framersandgr-blocksat. Usually/usr/local/lib64/python2.7/site-packageson RedHat/Fedora or/usr/local/lib64/python2.7/dist-packageson Ubuntu.- Ensure your
LD_LIBRARY_PATHenvironment variable is set. Typically/usr/local/lib64.
-
Once
blocksat-rx-guiis running, the first objective is to recognize the Blockstream Satellite signal band on the plots that are presented in the Overview tab of the GUI. Ideally, you would see a flat level spanning a frequency band (in the horizontal axis) of approximately 250 kHz, which corresponds to Blockstream Satellite's nominal system bandwidth. -
If you cannot see the signal using your initial pointing parameters, try several small adjustments of elevation and azimuth around the angles that were given to you by the dish alignment tool. For example, keep the elevation angle fixed and very slowly move the antenna side to side (vary the azimuth angle). Alternatively, keep azimuth fixed and slowly vary the elevation.
You can organize the procedure as follows. First change your elevation by 1 degree. Then, sweep the antenna left and right through a wide azimuth range. Repeat this until you are able to find the signal.
REMEMBER:
Even though a single degree may seem like a minuscule movement, each degree represents thousands of kilometers over the geosynchronous orbit.
The screenshot below illustrates the signal band visible at both the "Spectrum" and "Spectrogram" plots of the Overview GUI tab. The signal on the right-hand side is roughly from 50 kHz to 300 kHz, so it looks like our signal. Importantly, note that in this case (captured on Eutelsat 113) there is also a nearby transmission on the left-hand side of the plot. Although by inspection we can tell that this other signal is not ours, the only way to really know this is by checking the frame synchronization, which is the next step.
- Switch to the
Frame Synctab in the GUI. You should expect to see a clear peak there, as follows.
The peak can be toggling up and down and alternating colors, blue and red. What is really important is that it is strong and remains steadily in the same position. It can be in any position within the plot window, but it must remain in the same position for the system to be reliable.
If a steady peak has indeed been achieved, it is very likely that your receiver has acquired the so-called "frame synchronization" state. Have a look at the logs in the terminal. You should see the following message:
##########################################
-- Frame synchronization acquired
Furthermore, at this point, the following message is expected to be printed periodically in the console:
--------------------------------------------------------------------------------
[Timestamp] Frame Timing => LOCKED Timing Indicator: STRONG
--------------------------------------------------------------------------------
If frame synchronization has not yet been acquired, you can do some
troubleshooting. If you see a clear signal at the Overview tab of the GUI, first
check the frequency offset of the signal. The receiver can correct a frequency
offset within +- 250 kHz. If the signal band is centered at a frequency beyond
this range, the options are 1) to re-launch the receiver with a different
frequency; or 2) to re-launch the receiver in scan mode, specifically by
adding -s flag to the blocksat-rx-gui command, as follows:
blocksat-rx-gui -f 1276150000 -s
The scenario of a frequency offset exceeding the correction range is illustrated
in the screenshot above. Note that the signal band is clearly visible. However,
it is centered at approximately -325 kHz. Thus, the frequency recovery
algorithm cannot correct the frequency and, as a result, frame synchronization
is not acquired. This situation can also be diagnosed by looking at the
"Freq. Sync" page of the GUI. The goal is to have the "red curve" (spectrum
after frequency correction) centered around the origin of the horizontal axis,
as illustrated below. However, if the signal center frequency is beyond the
correction limit, this won't be the case. As mentioned earlier, either adjust
the frequency parameter of the receiver or re-launch it in scan mode.
Now, if the signal band is clear and centered within +-250 kHz, but you still
can't see a peak in the "Frame Sync" page or, correspondingly, you can't get
Frame synchronization acquired log in the console, it is possible that you are
seeing the wrong signal or pointed to the wrong satellite. If you see two
similar signal bands, both with an apparent 250 kHz flat level span, try
adjusting the frequency parameter such that only one of them is "visible" at a
time, based on the spectrum plots of the Overview tab. If that doesn't work,
then it is likely not a signal problem, but rather a satellite problem. Try
adjusting azimuth and/or elevation again to see if you can find a different
satellite near the nominal angles that you got from the dish alignment tool.
ATTENTION: In Europe, there is a nearby satellite that transmits a similar signal band on a similar frequency. Use the above instructions and particularly the "Frame Sync" tab of the GUI in order to know when pointed correctly.
- Now that frame synchronization has been acquired, we are mostly done. At this point, we can only pursue some improvements to the signal quality.
As a sanity check, switch to the Phase Sync page. You should see a
constellation composed by two clouds of points, one close to "-1" and the other
close to "+1". The more compact the point clouds are, the better your signal
quality.
To evaluate signal quality, the easiest way is to check the SNR that is being printed in the console, as below:
[Timestamp] SNR [================ ] 7.4401 dB
[Timestamp] SNR [================ ] 7.5041 dB
[Timestamp] SNR [================ ] 7.3762 dB
[Timestamp] SNR [================ ] 7.3644 dB
[Timestamp] SNR [================ ] 7.4068 dB
Keep an eye on these logs and then make very gentle adjustments to elevation, azimuth and/or LNB skew. You can try adjusting all three parameters, but the recommended approach is to try adjusting only one of them at a time. Make a small change and check whether it has improved the SNR. Try to stop at the optimal point in all of them.
- Lastly, with the antenna pointing and LNB polarization fixed, we recommend performing some quick experiments with the gain parameter of the receiver. This is a command line argument to the receiver application. Try different values between 0 and 50 and see if the SNR improves, for example:
# Attempt 1
blocksat-rx-gui --freq 1276150000 --gain 35
# Attempt 2
blocksat-rx-gui --freq 1276150000 --gain 45
Well done. Your receiver is properly set-up and you are now ready to run it continuously. You have two options now:
- Continue running in GUI mode, namely the above
blocksat-rx-guiapplication. - Run the lightweight non-GUI receiver application, named
blocksat-rx.
In case you are interested in learning more about technical aspects of the receiver and particularly understanding the performance metrics that are displayed in the GUI, please visit the Understanding the GUI guide guide in this wiki.
After installing the Blockstream Satellite receiver, a few receiver applications
become available in the system. The two main applications are named
blocksat-rx-gui and blocksat-rx. These run the full receiver, with and
without the GUI, respectively. The other applications are explained later in
this guide.
In order to launch the receiver in GUI mode, run:
blocksat-rx-gui -f [freq_in_hz]
freq_in_hz is the frequency parameter, specified in units of Hz.
See the Antenna Pointing Section for the computation of the frequency parameter.
Example:
blocksat-rx-gui -f 1276150000
You can see a full list of optional parameter using the help:
blocksat-rx-gui -h
In order to run the lighter receiver that does not provide any GUI (only console logs), execute:
blocksat-rx -f [freq_in_hz]
Example:
blocksat-rx -f 1276150000
The above frequency passed as argument -f to the receiver application
corresponds to the nominal (the ideal) frequency for your receiver. However, in
practice, the LNB deviates and does not place the satellite signal in this exact
frequency. This behavior is perfectly acceptable and is solved by the frequency
correction algorithm that runs in the Blockstream Satellite receiver, which can
correct up to an error of approximately +- 200 kHz.
However, depending on the quality of your LNB, it is possible that the error
exceeds the correctable range. In this case, in order to find the satellite
signal during the receiver initialization, you should run in scan mode. This
will sweep a wider range of frequencies and stop as soon as the Blockstream
Satellite signal is found. By default, this procedure can take up to a bit more
than a minute, but will likely complete earlier, depending on the magnitude of
the frequency error introduced by your hardware. Also, by default it sweeps a
range of approximately 3.5 MHz around the nominal frequency.
To run in scan mode, use the -s flag in either the blocksat-rx-gui,
blocksat-rx or blocksat-rx-lower (see below) application:
blocksat-rx -f 1276150000 -s
If the specs of your LNB guarantee an error/stability that is less than +- 1.75 MHz (check the specification for “Stability” or “L.O. Stability”), then you can
configure a narrower search range to ensure a faster scan. For example:
blocksat-rx -f 1276150000 -s -n 4
Argument -n above determines the number of scan iterations. In this
case, it is reduced from 8 (default value) to 4, so that a range of
approximately 1.75 MHz (+- 0.875 MHz) is scanned.
For more options, check the help:
blocksat-rx -h
The split receiver mode is intended to support the case where one computer (SDR host) is connected to the SDR/LNB/dish and the data is ultimately supposed to be processed at another host. This can be useful when, due to space and cabling limitations, it is preferable to use a small form factor computer connected to the antenna.
In this mode, the receiver stack is split between the SDR host and the PC. The SDR host implements the lower part of the stack, namely the layer that is closer to the physical medium. The other host, then, implements the upper part of the stack and delivers the data to the Bitcoin FIBRE application. They communicate to each other via TCP/IP.
To use this setup, first, in the SDR host, run:
blocksat-rx-lower -f [freq_in_hz] -i [IP] -p [Port]
where [ip] should be set to the IP address of the local
network interface and port is the TCP port to be used.
NOTE:
- The
blocksat-rx-lowerapplication behaves as TCP server, so it should be executed first.- In case multiple network interfaces are used in the SDR host, make sure to use the IP address of the interface that is in the same network of the PC.
Then, in the PC, run:
blocksat-rx-upper -i [Server IP] -p [Server Port]
where [Server IP] and [Server Port] are the ones that were used for the
blocksat-rx-lower application (i.e. the TCP server address/port).
NOTE:
- The upper Rx behaves as client to the TCP server opened in the lower Rx.
- The receive data flow streamed from the SDR host to the PC requires around 10 to 12 Mbps.
Example:
SDR host:
blocksat-rx-lower -f 1276150000 -i 10.0.0.1 -p 5201
PC:
blocksat-rx-upper -i 10.0.0.1 -p 5201
GUI Mode:
There are also Rx Lower and Rx Upper applications featuring a real-time GUI for
debugging and monitoring. These are named with -gui suffix. Following the
above example, the GUI applications would be launched similarly by:
SDR host:
blocksat-rx-lower-gui -f 1276150000 -i 10.0.0.1 -p 5201
PC:
blocksat-rx-upper-gui -i 10.0.0.1 -p 5201
In case you don't have Bitcoin FIBRE installed, do so before proceeding. Make sure to use the master branch, which is the one currently being used by the Blockstream Satellite transmitter.
For more information about Bitcoin FIBRE, refer to:
Bitcoin FIBRE: http://bitcoinfibre.org
Also, build instructions can be found here.
Note that the Blockstream Satellite receiver feeds received data into an output
named pipe that is supposed to be read by the Bitcoin FIBRE application. Hence,
you need to point FIBRE to the named pipe file accordingly. You can start
bitcoind with the following parameters:
bitcoind -fecreaddevice=/tmp/blocksat/bitcoinfibre
NOTE 1: The Blockstream Satellite receiver will create the
/tmp/blocksat/bitcoinfibrefile.
NOTE 2: Bitcoin Fibre uses the same
bitcoin.confconfiguration file as Bitcoin Core. Configure as needed.
Example Python applications for interaction with the Satellite API are available
in the api/examples directory. Please refer to the documentation
there.
For more information regarding the Satellite API, please visit
blockstream.com/satellite-api or the
documentation in the api directory.
Blockstream Satellite v1.4.0 or later is confirmed to work with Raspberry Pi 3 B+ using Ubuntu MATE 18.04.02 for 64-bit architecture. To install on Raspberry, proceed with the following steps:
- Download Ubuntu MATE Bionic for aarch64 (ARMv8).
- Flash the Ubuntu MATE OS into your microSD card. You can use a tool such as balenaEtcher.
- Run Raspberry Pi and install Blockstream Satellite there as usual. Follow the binary package installation instructions for Ubuntu.
- Compile bitcoin FIBRE for Raspberry Pi. You can compile natively on Raspberry Pi or cross-compile (recommended). Assuming the latter, first cross-compile the dependencies, then cross-compile the main apps.
- Ship the cross-compiled bitcoin FIBRE applications to Raspberry Pi.
- Run
blocksat-rxandbitcoinas usual.
NOTE: we recommend running the non-GUI (
blocksat-rx) application, due to CPU limitations. You can use the GUI app (blocksat-rx-gui) for pointing the dish, but once pointed, you should switch toblocksat-rx.
The commands in the sequel can be used for bitcoin FIBRE's cross-compilation
from an Ubuntu 18.04 x86 (amd64) machine, targeting the Raspberry Pi's 3 B+
64-bit processor armv8 (aarch64).
First install the aarch64 toolchain:
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu
Then, from bitcoinfibre's root folder, run:
cd depends
make HOST=aarch64-linux-gnu NO_QT=1
cd ..
./autogen.sh
./configure --prefix=$PWD/depends/aarch64-linux-gnu --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++
make CXXFLAGS='-pipe -O2 -fvisibility=hidden -DLINUX_ARM -DHAVE_ARM_NEON_H -DGF256_TRY_NEON'
Finally, ship the built applications such as src/bitcoind and
src/bitcoin-cli to Raspberry Pi.
-
No binary package available for GNU Radio 3.7.10 or later
If a package is not available for 3.7.10+, we recommend either looking for a repository that includes such a version or installing via PyBOMBS. For the latter, see the instructions in the PyBOMBS repository.
-
Error during build: could not find
GnuradioConfig.cmakeorgnuradio-config.cmake.The complete error is Could not find a package configuration file provided by "Gnuradio" with any of the following names:
GnuradioConfig.cmake, gnuradio-config.cmake.These tools are needed in order to build the modules that are used by the receiver (at
satellite/gr-blocksat/). The role of these scripts is thoroughly described in the GNU Radio wiki . As explained there, these files are found in$prefix/lib/cmake/gnuradio, where$prefixis the path where GNU Radio is installed (e.g./usr/local). If not sure about your own prefix, run:gnuradio-config-info --prefixThen, check whether
GnuradioConfig.cmakeorgnuradio-config.cmakeis available there in thelib/cmake/gnuradiofolder. If not, it is likely that you need to install a separate GNU Radio development package. These are namedgnuradio-develorgnuradio-dev, depending on distro. For example, on Fedora, use:sudo dnf install gnuradio-devel -
Block key "rtlsdr_source" not foundThis can occur in case the
gr-osmosdrpackage is not installed, so you should double check this first.Also, it can happen in case you have multiple GNU Radio installations, with conflicting
grc.conffiles. To verify whether this is the case, first check if "rtlsdr_source" is indeed missing. Search forrtlsdr_source.xml:sudo find / -name *rtlsdr_source.xmlIf GNU Radio is installed in prefix
/usr/local, you would see it there:/usr/local/share/gnuradio/grc/blocks/rtlsdr_source.xmlNow, check the paths for GNU Radio blocks in each of your
grc.conffiles. In particular, check if the abovertlsdr_sourcepath is included. You can use:sudo find / -name grc.conf -exec \ echo -e "\nBlock paths at {}:\n" \;\ -exec grep "blocks_path" {} \;If
rtlsdr_source.xmlexists and agrc.confpoints to its path, ensure that your GNU Radio Companion instance is loading thisgrc.conf. -
Error during build No rule to make target
swig/framers_swig.py:The complete error message is:
No rule to make target 'swig/framers_swig.py', needed by 'swig/framers_swig.pyc'. Stop. This refers to theframers_swig.pycfile, which is built and installed bymake framers; make install framers. If you are seeing this error and you can confirm that the referred file exists within your Pythonsite-packagesordist-packagesfolder (depending on distro), try building the Rx applications using parallel recipe execution, that is, using for example:make -j4 -
"CppUnit" required to compile blocksat
Install the development CppUnit library. For example, on CentOS, run:
sudo yum install cppunit-devel -
Error
‘list’ object has no attribute ‘get’on headless CentOS build.The build of the Rx applications (launched by
make) relies on the GNU Radio Companion Compiler ("grcc") tool, which in turn requires a display server. To overcome this on a headless environment, you can build using X virtual framebuffer (Xvfb).On CentOS, you can install Xvfb using:
sudo yum install xorg-x11-server-XvfbaThen, run "make" from inside a virtual window server using:
xvfb-run makeFurthermore, note that, in a headless environment, it is possible that your GNU Radio installation does not include QT GUI. You can double check that by launching an interactive Python shell and trying to import QT GUI:
from gnuradio import qtguiIf the above does not work, meaning you don't have QT GUI installed, the above build using
makeis still prone to failure. This is because the GUI-based Rx applications rely on QT GUI and the "grcc" tool attempts to find the GUI blocks during build. However, note that you can still build solely the non-GUI Rx applications. You can do so using:xvfb-run make GUI=0 -
Unable to locate gnuradio via
apt-getWhen trying to install
gnuradioin Ubuntu viaapt-get, you see:$ sudo apt-get install gnuradio Reading package lists... Done Building dependency tree Reading state information... Done E: Unable to locate package gnuradioThis is likely because "Universe" Ubuntu repositories are disabled. Proceed with the following steps:
- Open "System Settings", then "Software & Updates".
- Enable downloads from "Community-maintained free and open-source software (universe)".
- Close and reload.
-
Permission to access the RTL-SDR dongle
When running the receiver, your user needs to have permission to access the RTL-SDR. Try running
rtl_testand check if it works. If it does not, butsudo rtl_testdoes work, you should configure your udev rules for your RTL-SDR device, see the list of rules in the RTL-SDR repository. If after that it still does not work for your user, you can try adding your user to thertlsdrgroup. That is:usermod -a -G rtlsdr your_user` -
ImportError: No module named xxx (for example "ImportError: No module named framers")
Make sure that the Blockstream Satellite receiver Python modules can be found in your system. Assuming 64-bit systems, the default path will either be
/usr/local/lib64/python2.7/site-packageson RedHat/Fedora or/usr/local/lib/python2.7/dist-packageson Ubuntu. Double check by looking into one of these directories and searching forframersandblocksatfolders.In case you can't find these folders, you can manually discover where the modules are located. For example, by running:
sudo find / -name *framers_swig.py*If, for instance, you verify that the modules are indeed located at
/usr/local/lib64/python2.7/site-packages/, then Python must be able to find modules in this path. You can check the directories on your Python path (including default paths) by running:python -c "import sys; print '\n'.join(sys.path)"In case the directory of interest is not included in the list by default, you can add it using the
PYTHONPATHenvironmental variable. This variable holds a colon-separated list of directories. In the given example, you would add the directory by executing:export PYTHONPATH=/usr/local/lib64/python2.7/site-packages:$PYTHONPATH -
If when running the receiver the program exits due to
segmentation fault, you can check whether this is related to the Blockstream Satellite GNU Radio out-of-tree (OOT) modules. By OOT modules, we mean theframersandblocksatmodules, the former within thegr-framersfolder and the latter within thegr-blocksatfolder of the root folder in this project. In the sequel, we will take theblocksatmodule as reference in the examples, but the same procedure applies to theframersmodule.Before starting to debug, ensure that
ldconfigis (or was) executed after module installation. This step is automatically executed when runningsudo make install-blocksatorsudo make install-framers. Hence, it can be skipped in case you installed the modules using the instructed "make install" commands (check the install logs).Next, you should verify that the "blocksat" (or "framers") module can be successfully imported in Python. To do so, run:
python2.7 -c "import blocksat"If nothing is printed, it means that the module can indeed be imported. The segmentation fault is likely not related to this module, so try the same on the other module ("framers"). In contrast, if you see segmentation fault, we advise to debug shared libraries.
There are two things to verify regarding shared libraries: 1) that they can be located and 2) that they can be correctly loaded. To double check that the blocksat shared libraries can be found, you can inspect the
lddoutput on the swig-generated shared library files. For example, assuming that your library path is at/usr/local/lib/python2.7/dist-packages(e.g. on Ubuntu), you can run:ldd /usr/local/lib/python2.7/dist-packages/blocksat/_blocksat_swig.so | grep blocksatIf your library is instead at
/usr/local/lib64/python2.7/site-packages(e.g. on Fedora), run:ldd /usr/local/lib64/python2.7/site-packages/blocksat/_blocksat_swig.so | grep blocksatThe above command should point to the shared library
.sofile. If, instead, you see "not found", double check that the location of the module's library is indeed being searched by the Linux program loader. First, check the directories listed or included in/etc/ld.so.conf. If the directory of interest is not in this list, you can include it by using theLD_LIBRARY_PATHenvironmental variable. This variable is a colon-separated set of directories, so that, for example, to add the path/usr/local/libyou can run:export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATHWhen the above
lddcommand already points to the shared library file, but theimport blocksatPython command still fails, then it is likely that the problem is in the library itself. This can be inspected by looking at the library loading logs. To do so, set theLD_DEBUGenvironmental variable tolibsand then attempt to import the module in Python. For example, for theblocksatmodule, run:LD_DEBUG=libs python -c "import blocksat" 2>&1 | grep "blocksat"Subsequently, check the occurrences of "blocksat" in the logs and check whether they are error-free. If not, then there is probably a problem in the source code. In this case, please feel free to raise an issue or contact us directly.