{"id":19624671,"url":"https://github.com/nature40/pyradiotracking","last_synced_at":"2025-06-10T22:33:40.075Z","repository":{"id":97594504,"uuid":"302846506","full_name":"Nature40/pyradiotracking","owner":"Nature40","description":"Detect signals of wildlife tracking systems with RTL SDR devices.","archived":false,"fork":false,"pushed_at":"2023-03-02T13:31:50.000Z","size":1549,"stargazers_count":15,"open_issues_count":7,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-28T05:35:25.560Z","etag":null,"topics":["movement-ecology","rtlsdr","vhf"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nature40.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-10T07:50:40.000Z","updated_at":"2025-04-09T02:29:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"f291e1aa-dadf-4e03-83c9-2a511329f93a","html_url":"https://github.com/Nature40/pyradiotracking","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nature40%2Fpyradiotracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nature40%2Fpyradiotracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nature40%2Fpyradiotracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nature40%2Fpyradiotracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nature40","download_url":"https://codeload.github.com/Nature40/pyradiotracking/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nature40%2Fpyradiotracking/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259164039,"owners_count":22815261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["movement-ecology","rtlsdr","vhf"],"created_at":"2024-11-11T11:38:39.097Z","updated_at":"2025-06-10T22:33:40.064Z","avatar_url":"https://github.com/Nature40.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"pyradiotracking\n===\n\nDetect signals of wildlife tracking systems with RTL SDR devices.\n\n### Usage\n\n```bash\n$ python3 -m radiotracking -h\nusage: radiotracking [-h] [-v] [--config CONFIG] [--station STATION] [--schedule [SCHEDULE [SCHEDULE ...]]] [-d [DEVICE [DEVICE ...]]]\n                     [-c [CALIBRATION [CALIBRATION ...]]] [-f CENTER_FREQ] [-s SAMPLE_RATE] [-b SDR_CALLBACK_LENGTH] [-g GAIN]\n                     [--sdr-max-restart SDR_MAX_RESTART] [--sdr-timeout-s SDR_TIMEOUT_S] [-n FFT_NPERSEG] [-w FFT_WINDOW] [-t SIGNAL_THRESHOLD_DBW]\n                     [-r SNR_THRESHOLD_DB] [-l SIGNAL_MIN_DURATION_MS] [-u SIGNAL_MAX_DURATION_MS] [--matching-timeout-s MATCHING_TIMEOUT_S]\n                     [-mt MATCHING_TIME_DIFF_S] [-mb MATCHING_BANDWIDTH_HZ] [-md MATCHING_DURATION_DIFF_MS] [--sig-stdout] [--match-stdout]\n                     [--path PATH] [--csv] [--export-config] [--mqtt] [--mqtt-host MQTT_HOST] [--mqtt-port MQTT_PORT] [--dashboard]\n                     [--dashboard-host DASHBOARD_HOST] [--dashboard-port DASHBOARD_PORT] [--dashboard-signals DASHBOARD_SIGNALS]\n\nDetect signals of wildlife tracking systems with RTL SDR devices\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --verbose         increase output verbosity (default: 0)\n  --config CONFIG       configuration file (default: etc/radiotracking.ini)\n  --station STATION     name of the station (default: test)\n  --schedule [SCHEDULE [SCHEDULE ...]]\n                        specify a schedule of operation, e.g. 18:00-18:59:59 (default: [])\n\nrtl-sdr:\n  -d [DEVICE [DEVICE ...]], --device [DEVICE [DEVICE ...]]\n                        device indexes or names (default: ['0'])\n  -c [CALIBRATION [CALIBRATION ...]], --calibration [CALIBRATION [CALIBRATION ...]]\n                        device calibration gain (dB) (default: [])\n  -f CENTER_FREQ, --center-freq CENTER_FREQ\n                        center frequency to tune to (Hz) (default: 150150000)\n  -s SAMPLE_RATE, --sample-rate SAMPLE_RATE\n                        sample rate (Hz) (default: 300000)\n  -b SDR_CALLBACK_LENGTH, --sdr-callback-length SDR_CALLBACK_LENGTH\n                        number of samples to read per batch (default: None)\n  -g GAIN, --gain GAIN  gain, supported levels 0.0 - 49.6 (default: 49.6)\n  --sdr-max-restart SDR_MAX_RESTART\n                        maximal restart count per SDR device (default: 3)\n  --sdr-timeout-s SDR_TIMEOUT_S\n                        Time after which an SDR device is considered unrepsonsive (s) (default: 2)\n\nanalysis:\n  -n FFT_NPERSEG, --fft-nperseg FFT_NPERSEG\n                        fft number of samples (default: 256)\n  -w FFT_WINDOW, --fft-window FFT_WINDOW\n                        fft window function (default: 'hamming')\n  -t SIGNAL_THRESHOLD_DBW, --signal-threshold-dbw SIGNAL_THRESHOLD_DBW\n                        lower limit for signal intensity (dBW) (default: -90.0)\n  -r SNR_THRESHOLD_DB, --snr-threshold-db SNR_THRESHOLD_DB\n                        lower limit for signal-to-noise ratio (dB) (default: 5.0)\n  -l SIGNAL_MIN_DURATION_MS, --signal-min-duration-ms SIGNAL_MIN_DURATION_MS\n                        lower limit for signal duration (ms) (default: 8)\n  -u SIGNAL_MAX_DURATION_MS, --signal-max-duration-ms SIGNAL_MAX_DURATION_MS\n                        upper limit for signal duration (ms) (default: 40)\n\nmatching:\n  --matching-timeout-s MATCHING_TIMEOUT_S\n                        timeout for adding signals to a match group (default: 2.0)\n  -mt MATCHING_TIME_DIFF_S, --matching-time-diff-s MATCHING_TIME_DIFF_S\n                        error margin for timestamp matching (s) (default: 0)\n  -mb MATCHING_BANDWIDTH_HZ, --matching-bandwidth-hz MATCHING_BANDWIDTH_HZ\n                        error margin for frequency (Hz) (default: 0)\n  -md MATCHING_DURATION_DIFF_MS, --matching-duration-diff-ms MATCHING_DURATION_DIFF_MS\n                        error margin for duration (ms) (default: None)\n\npublish:\n  --sig-stdout          enable stdout signal publishing (default: False)\n  --match-stdout        enable stdout matched signals publishing (default: False)\n  --path PATH           file output path (default: data)\n  --csv                 enable csv data publishing (default: False)\n  --export-config       export configuration (default: False)\n  --mqtt                enable mqtt data publishing (default: False)\n  --mqtt-host MQTT_HOST\n                        hostname of mqtt broker (default: localhost)\n  --mqtt-port MQTT_PORT\n                        port of mqtt broker (default: 1883)\n\ndashboard:\n  --dashboard           enable web-dashboard (default: False)\n  --dashboard-host DASHBOARD_HOST\n                        hostname to bind the dashboard to (default: localhost)\n  --dashboard-port DASHBOARD_PORT\n                        port to bind the dashboard to (default: 8050)\n  --dashboard-signals DASHBOARD_SIGNALS\n                        number of signals to present (default: 100)\n```\n\n### Troubleshooting\n\n#### Failed to allocate zero-copy buffer\n\nThe size of zero-copy kernel buffers is limited.\n\n```\nFailed to allocate zero-copy buffer for transfer 5\nFalling back to buffers in userspace\nFailed to submit transfer 6\nPlease increase your allowed usbfs buffer size with the following command:\necho 0 \u003e /sys/module/usbcore/parameters/usbfs_memory_mb\n```\nFor larger buffers, as preferable for high sampling rates in terms of effificiency, the usbfs memory limit can be removed:\n\n`echo 0 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb`\n\n#### Clock Drift, Resyncing\n\nEach analyzer holds a time stamp internally to derive the time of a detected signal from. The clock is initialized on first async callback from the RTL-SDR library and then incremented according to the data retrieved from the SDR in the following callbacks. Whenever the calculated timestamp differs from the system clock by more than one block length this is detected:\n\n`SDR 0 total clock drift (1.1482 s) is larger than two blocks, signal detection is degraded. Resyncing...`\n\nResyncing resets the internal clock to the current system clock, such that even though samples have been lost, the detected signals are using the correct timestamp.\n\n\u003e Whenever resyncing is happening, there is a high likelihood, that signals detected in the previous blocks are also undergoing delay. \n\nResyncing can be prevented by using less ressource hungry settings, such as: higher signal / SNR thresholds, lower gain, lower sampling rate, larger callback length. \n\n\n### Caveats\n\n- The sample rate of RTL-SDR is [limited to certain numbers](https://github.com/osmocom/rtl-sdr/blob/0847e93e0869feab50fd27c7afeb85d78ca04631/src/librtlsdr.c#L1103-L1108) in 225 kHz - 3.2 GHz, excluding 300 kHz - 900 kHz.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnature40%2Fpyradiotracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnature40%2Fpyradiotracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnature40%2Fpyradiotracking/lists"}