https://github.com/pierregode/mmm-deepspacesignals

Last synced: 8 months ago
JSON representation

Host: GitHub
URL: https://github.com/pierregode/mmm-deepspacesignals
Owner: PierreGode
License: mit
Created: 2025-06-28T22:44:37.000Z (12 months ago)
Default Branch: main
Last Pushed: 2025-06-28T23:07:12.000Z (12 months ago)
Last Synced: 2025-06-29T00:19:07.196Z (12 months ago)
Language: JavaScript
Size: 4.88 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# 🛰️ MMM-DeepSpaceSignals

A MagicMirror² module that polls various astronomy data sources for new and unusual signals.
It can show recent **Fast Radio Bursts**, **gravitational wave alerts**, and **pulsar observations**.
It can also display the latest **NASA Astronomy Picture of the Day (APOD)**.

---

## 🛠️ Installation

```bash
cd ~/MagicMirror/modules
git clone https://github.com/PierreGode/MMM-DeepSpaceSignals
cd MMM-DeepSpaceSignals
npm install
```

The module uses a Node helper to fetch data server-side. Your configuration is sent to the helper when the module starts, and it handles periodic updates.

---

## 🔄 Update

```bash
cd ~/MagicMirror/modules/MMM-DeepSpaceSignals
git pull
npm install
```

---

## 🐍 Optional: Python Pulsar Support (ATNF Fetcher)

If the optional Python dependencies are installed, the Node helper will run
`pulsar_fetcher.py` automatically the first time it needs a local
`pulsars.json` file. The script now writes this file to the module directory so
the helper can load it without needing a specific working directory. You can
also point `apiUrls.pulsar` directly to a Python script (e.g. `fetch_pulsars.py`).
If the URL ends with `.py`, the helper executes the script and expects JSON on
stdout. Install the required packages, for example on Raspberry Pi:

```bash
pip install psrqpy astropy --break-system-packages
```

The example scripts query the ATNF catalogue and either write the results to
`pulsars.json` or output JSON directly.

If your Python script emits runtime warnings to stdout, earlier versions of the
helper could fail with a **"Pulsar unrecognized content"** message. The helper
now trims non‑JSON lines before parsing so such warnings no longer break the
parsing step.

---

## ⚙️ Configuration

Add the module to the `modules` array in `config.js`:

```javascript
{
module: "MMM-DeepSpaceSignals",
position: "top_right",
config: {
updateInterval: 10 * 60 * 1000,
maxWidth: "340px",
sources: {
frb: true,
gravitational: true,
pulsar: false,
apod: true
},
apiUrls: {
frb: "data/frb_sample.json",
frbBackup: null,
gravitational: "https://gwosc.org/eventapi/jsonfull/allevents/",
pulsar: "fetch_pulsars.py",
apod: "https://api.nasa.gov/planetary/apod?api_key=*****"
},
minStrength: {
frb: null,
gravitational: null,
pulsar: null,
apod: null
}
}
}
```

`intensity` values depend on the data source:
- FRB events use **fluence (Jy·ms)**
- Gravitational waves show **significance**
- Pulsars may report **signal-to-noise ratio (SNR)**

### Intensity Levels

The value in the **Intensity** column is color‑coded to make reading the table easier:

| Fluence (Jy·ms) | Interpretation | Notes |
|-------------------|---------------|-------|
| < 1 | Very weak | Hard to detect, may be near background noise |
| 1 – 5 | Weak to moderate | Common range for many typical FRBs |
| 5 – 20 | Moderate to strong | Likely detectable with medium-sized radio arrays |
| > 20 | Strong or rare | May indicate nearby or unusually energetic source |
| > 100 | Extremely strong (rare) | Often referred to as "giant bursts" or hyperflares |

---

## 🧠 Signal Types Explained

This module detects and displays multiple types of deep space signals. Here's what each one means:

### 💥 FRB – Fast Radio Burst
Fast Radio Bursts are extremely brief but powerful pulses of radio waves from deep space.
- Duration: milliseconds
- Possible sources: magnetars, neutron stars, or unknown phenomena
- Measured in **fluence** (Jy·ms)
- Often mysterious and still under research

### 🌊 GE – Gravitational Events (Gravitational Waves)
Gravitational waves are ripples in the fabric of spacetime, typically caused by:
- Colliding black holes
- Merging neutron stars
- Detected by observatories like **LIGO** and **Virgo**
- Strength is indicated by a **significance score** or **FAP** (False Alarm Probability)

### 🌟 Pulsar
Pulsars are fast-rotating neutron stars that emit beams of electromagnetic radiation.
- Often observed as regular pulses (like a cosmic lighthouse)
- Identified by **SNR** (Signal-to-Noise Ratio), rotation speed, or pulse period
- Useful for studying extreme physics like gravity and magnetism

---

## 🌐 Data Sources

The helper polls the following public APIs:

| Source | Description | API Key Required |
|-----------------|-------------------------------------|------------------|
| **CHIME/FRB** | Recent Fast Radio Burst detections | ❌ No |
| **CHIME/FRB (backup)** | Mirror of FRB events | ❌ No |
| **LIGO/Virgo** | Gravitational wave alerts | ❌ No |
| **ATNF Pulsars**| Pulsar observations (JSON or script)| ❌ / Optional |
| **NASA APOD** | Daily astronomy image + caption | ✅ Yes (free) |

> When enabled, the module displays the APOD image and its explanation directly in the table if the media type is an image. The image is constrained to a maximum width of 200 px to fit nicely inside the module. If the caption is longer than 10 lines it appears in a scrollable box that scrolls over 40 seconds and then pauses for 10 seconds before restarting.

If the primary FRB endpoint is unreachable (e.g., 404 error), the module
tries the `frbBackup` URL. If that also fails, it loads the local file
`data/frb_sample.json`.

To get your own NASA API key, visit: [https://api.nasa.gov/](https://api.nasa.gov/)

---

## 📃 License

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pierregode/mmm-deepspacesignals

Awesome Lists containing this project

README