{"id":13576454,"url":"https://github.com/cariboulabs/cariboulite","last_synced_at":"2025-05-14T17:02:56.101Z","repository":{"id":37249170,"uuid":"376525310","full_name":"cariboulabs/cariboulite","owner":"cariboulabs","description":"CaribouLite turns any 40-pin Raspberry-Pi into a Tx/Rx 6GHz SDR","archived":false,"fork":false,"pushed_at":"2025-02-15T06:16:53.000Z","size":245669,"stargazers_count":1190,"open_issues_count":106,"forks_count":118,"subscribers_count":61,"default_branch":"main","last_synced_at":"2025-04-13T06:17:03.405Z","etag":null,"topics":["defined","fpga","ice40","icestorm","pi","radio","raspberry","rf","rpi","sdr","software","yosys"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cariboulabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2021-06-13T11:33:37.000Z","updated_at":"2025-04-12T01:28:36.000Z","dependencies_parsed_at":"2025-01-31T04:40:52.927Z","dependency_job_id":"b3960bef-fd7f-4354-b6db-d6817cfceb96","html_url":"https://github.com/cariboulabs/cariboulite","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/cariboulabs%2Fcariboulite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cariboulabs%2Fcariboulite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cariboulabs%2Fcariboulite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cariboulabs%2Fcariboulite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cariboulabs","download_url":"https://codeload.github.com/cariboulabs/cariboulite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190368,"owners_count":22029631,"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":["defined","fpga","ice40","icestorm","pi","radio","raspberry","rf","rpi","sdr","software","yosys"],"created_at":"2024-08-01T15:01:10.353Z","updated_at":"2025-05-14T17:02:55.983Z","avatar_url":"https://github.com/cariboulabs.png","language":"C","funding_links":[],"categories":["C","LP1K"],"sub_categories":[],"readme":"# CaribouLite\nCaribouLite is an affordable, educational, open-source SDR evaluation platform and a HAT for the Raspberry-Pi family of boards (40-pin versions only). It is built for makers, hackers, and researchers and was designed to complement the current SDR (Software Defined Radio) eco-systems offering with a scalable, standalone dual-channel software-defined radio.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/oshwa.png\" alt=\"Open source hardware association certificate\"\u003e\u003c/td\u003e\n    \u003ctd\u003eThis project has been certified by OSHWA\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/DSC_1151.jpg\" alt=\"CaribouLite R2\" height=\"200\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eCaribouLite R2.5 SDR mounted on a RPI-Zero\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## NOTE: No Support for RPI-5\nDue to the architectural changes in RPI5 - the new I/O controller called \"RP1\" chip, CaribouLite is not supported on RPI5. We assume that the reason is the removal of the SMI interface altogether from the external interfaces by Broadcomm's team.\nSo, if you intend to use CaribouLite on RPI5 please don't - it won't work. Why was the SMI interface deprecated by Broadcomm (either from its hardware or kernel SW support)? Most probably due to the same reason this interface was not documented in the first place - no interest in supporting a high-speed external interface within the 40-pin connector.\n\nEdit: The workaround we are working to support RPI5 anyway - trying to utilize the Display and Camera I/O pins from the 40-pin connector to stream information - FPGA + Kernel module adaptation.\n\n# Getting Started \u0026 Installation\nUse the following steps to install the CaribouLite on your choice of RPI board\n1. Mount the CaribouLite on a **un-powered** RPI device using the 40-pin header.\n2. Power the RPI device, wait for it to finish boot sequence.\n3. Clone this repository into a local directory of your choise (in this case `~/projects`)\n```\nmkdir ~/projects\ncd ~/projects\ngit clone https://github.com/cariboulabs/cariboulite\ncd cariboulite\n```\n4. Use the following setup command (**note: don't `sudo` it**):\n    ```\n    install.sh\n    ```\n\nThe setup script **requires internet connection** and it follows the following automatic steps:\n1. **Dependencies** installation (apt)\n2. **Soapy API tools installation** (SoapySDR and SoapyRemote) - only if they are not currently present in the system. Installation from code.\n3. **Internal dependencies installation**\n   1. Utilities and tools\n   2. IIR DSP library\n   3. SMI stream device module (kernel object) blob generation\n4. **Main software** and SoapyAPI compilation and installation\n5. **Raspberry PI configuration** verification. Note - the installer doesn't not actively change the RPI's configuration to fit to CaribouLite. It just checks the `/boot/config.txt` configuration file and raises warning when problem is detected. Then the user shall need to adjust the parameters accordingly.\n\nNote: the user will be requested to enter their password during the installation process.\n\n## Installation Troubleshooting\n1. **Modules**: Both the `spi` and `arm-i2c` dtoverlays should be disabled to run CaribouLite properly. The `libcariboulite` doen't use them. It uses direct access to `/dev/mem` to expose these peripherals (through the `pigpio` library).\nThe interfaces can be disabled (or enabled back whenever needed) by either directly editing the `/dev/config.txt` file or by using the `sudo raspi-config` command. The latter is the preferred choice as it is straight forward, less error prone and it works on all RaspberryPi's OS distributions (including DragonOS).\nIf the direct editing path has been chosen (`/boot/config.txt`), the following lines\nshould be commented out:\n`#dtparam=spi=on`\n`#dtparam=i2c_arm=on`\n\n2. **Kernel headers** - `libcariboulite` loads a custom kernel module (`smi_stream_dev`) during startup. The kernel module sources are location in : **`/software/libcariboulite/caribou_smi/kernel`**. Recompilation of these .ko obejcts is needed whenever software is pulled. This requires currently to have the local host system to have the kernel headers installed. In addition, upgrading the kernel will require recompilation with the updated kernel headers. Once the `smi_stream_dev` is listed inside the main kernel tree, this process will become redundant.\n\n3. **sudo**ing - Currently hardware is accessed through the PIGPIO library. It should be given a root access to control the low level interfaces through the `/dev/mem` device. The relevant part of the software that is concerned in this matter is the \"io_utils\" sub-module. Once this module is re-designed to access the hardware through the \"gpiomem\" and \"spidev\" modules, this restrictions shall be mitigated (by the definitions of `udev` rules).\nSo currently, sudo'ing is needed whenever CaribouLite is accessed (including sudo'ing python...).\n\n\nTo compile the API library and SoapySDR API from code please click [here](/software/libcariboulite/README.md)\n\n# SMI Interface\n\nUnlike many other HAT projects, CaribouLite utilizes the **SMI** (Secondary Memory Interface) present on all the 40-pin RPI versions. This interface is not thoroughly documented by both Raspberry-Pi documentation and Broadcomm's reference manuals. An amazing work done by [Lean2](https://iosoft.blog/2020/07/16/raspberry-pi-smi/) (code in [git repo](https://github.com/jbentham/rpi)) in hacking this interface has contributed to CaribouLite's technical feasibility. A deeper overview of the interface is provided by G.J. Van Loo, 2017 [Secondary_Memory_Interface.pdf](docs/smi/Secondary%20Memory%20Interface.pdf). The SMI interface allows exchanging up to ~500 Mbit/s (depending on the FPGA, data-bus width, etc.) between the RPI and the HAT, and yet, the results vary between the different versions of RPI. The results further depend on the specific RPI version's DMA speeds.\n\nThe SMI interface can be accessed from the user space Linux applications as shown in [Lean2](https://iosoft.blog/2020/07/16/raspberry-pi-smi/), but Broadcomm also provided a neat minimal charachter device interface in the `/dev` directory using the `open`, `close`, `write`, `read`, and `ioctl` system calls. More on this interesting interface in the [designated readme file](software/libcariboulite/src/caribou_smi/index.md). This device driver needs to be loaded using `modprobe`.\n\nMore information on this interface can be found [here (HW side)](docs/smi/README.md) and [here (SW side)](software/libcariboulite/src/caribou_smi/README.md).\n\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/DSC_1102.jpg\" alt=\"Top View\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eCariboulite /w RPI Zero, two channels occupied\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n# Hardware Revisions\nThe board first prototyping (**Red**) revision ([REV1](hardware/rev1)) has been produced and tested to meet our vision on the board's capabilities. This revision was used to test its RF parts, the digital parts, and to develop its firmware and software support over the RPI.\n\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev1/DSC_1044.jpg\" alt=\"CaribouLite R1\" width=\"500\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/Rev2.5/front_rfi.png\" alt=\"CaribouLite Connectors\" width=\"500\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eCaribouLite Rev1 - the prototype version\u003c/td\u003e\n    \u003ctd\u003eCaribouLite Rev2.5 - Production Revision\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nThe second revision ([REV2](hardware/rev2)) - **White** - was then designed to further refine the design as described below:\n1. Image rejection filtering improvement - U10 and U12 (HPF \u0026 LPF) - have been replaced by integrated LTCC filters by MiniCircuits with much better out-of-band rejection than the former ones.\n2. Removing FPGA flash - redundant given the fact that the the RPI configures the FPGA in \u003c1sec over SPI. Even if we have a whole library of custom made FPGA firmware files, switching between them is as simple and fast as a single linux command.\n3. Board layout improvements and overlays (silkscreen) beautification (including logo).\n4. A single system level 3.3V power (while the FPGA still receives 2.5V and 1.2V for its core). A linear regulator (rather than a switching DC-DC) was used to reduce conducted (power and ground) noise levels.\n5. Top and bottom EMI sheilding option - the EMI/RFI shield design models are provided in the [3d directory](hardware/rev2/3d/)\n6. More detailed changes in the [schematics](hardware/rev2/schematics/cariboulite_r2_sch.PDF).\n\nIn summary, in CaribouLite-Rev2.5 PCB design has been thoroughly re-thought to meet its educational needs with performance in mind. The RF path has been annotated with icons to ease the orientation in the schematics sheets, friendly silk writing was added describing system's components by their functionality rather than logical descriptors, and more.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/DSC_1127.jpg\" alt=\"Top View\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/DSC_1132.jpg\" alt=\"Top View\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eTop and Bottom views of CaribouLite \u003cb\u003eRev2.4\u003c/b\u003e (pre-production)\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/Rev2.5/front_exposed.png\" alt=\"Top View\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/Rev2.5/front_rfi.png\" alt=\"Top View\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/Rev2.5/back_exposed.png\" alt=\"Top View\"\u003e\u003c/td\u003e\n  \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev2/pictures/Rev2.5/back_rfi.png\" alt=\"Top View\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eTop and Bottom views of CaribouLite \u003cb\u003eRev2.5\u003c/b\u003e\u003c/td\u003e\n    \u003ctd\u003eTop and Bottom views of CaribouLite \u003cb\u003eRev2.5\u003c/b\u003e with EMI/RFI shields\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n# Specifications\n\n\u003cB\u003eRF Channels:\u003c/B\u003e\n- Sub-1GHz: 389.5-510 MHz / 779-1020 MHz\n- Wide tuning channel: 30 MHz - 6 GHz (excluding 2398.5-2400 MHz and 2483.5-2485 MHz)\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/cariboulabs/cariboulite_hw/blob/main/hardware/rev1/frequencies.png\" alt=\"spectra\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center\"\u003eApplicable spectra, S1G - sub-1GHz, WB - Wide tuning channel\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003cB\u003eNote\u003c/B\u003e:\nThe gaps are defined by the design constraints of the system and may not exist in real-life hardware. Actual modem synthesizer outputs test show wider margins at room temperature than those written in the datatsheet, but, as noted by Microchip, performance may suffer.\n\n\n\u003cB\u003eFPGA specifications:\u003c/B\u003e\n- 160 LABs / CLBs\n- 1280 Logic Elements / Cells\n- 65536 Total RAM bits\n- 67 I/Os, Temp: -40-100 degC\n\n\u003cB\u003eApplicable RPI models\u003c/B\u003e: RPI_1(B+/A+), RPI_2B, RPI_Zero(Zero/W/WH), RPI_3(B/A+/B+), RPI_4B\n\nParameter                  |  Sub-1GHz                    | Wide Tuning Channel\n---------------------------|------------------------------|------------------------------------------------------------------\nFrequency tuner range      | 389.5-510 MHz / 779-1020 MHz | 30 MHz - 6 GHz (excluding 2398.5-2400 MHz and 2483.5-2485 MHz)\nSample rate (ADC / DAC)    | 4 MSPS                       | 4 MSPS\nAnalog bandwidth (Rx / Tx) | 2.5 MHz                      | 2.5 MHz\nMax Transmit power         | 14 dBm                       | \u003e10 dBm @ 30-2400 MHz, \u003e5 dBm @ 2400-6000 MHz\nReceive noise figure       | \u003c5 dB                      | \u003c6 dB @ 30-3500 MHz, \u003c8 dB @ 3500-6000 MHz\n\n\u003cB\u003eNote\u003c/B\u003e:\n(1) Feature comparison table with other SDR devices will be published shortly\n(2) Some of the above specifications are simulated rather than tested\n(3) Analog bandwidth controlled by the modem\n(4) The ISM version of the board doesn't contain the wide-range of frequencies (30-6000 MHz) and contains the native capabilities of the Modem IC.\n\n# Disclaimer\nCaribouLite is a test equipment for RF systems. You are responsible for using your CaribouLite legally.\n\nDefinitions: THE SUBJECT CONTENT: all files, software, instructions, information, ideas and knowledge located in this git repository.\n\nNo Warranty: THE SUBJECT CONTENTS ARE PROVIDED \"AS IS\" WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT CONTENTS WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT CONTENTS WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT CONTENTS. FURTHER, THE REPOSITORY OWNERS AND CONTRIBUTORS DISCLAIM ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTE IT \"AS IS.\"\n\nWaiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE REPOSITORY OWNERS AND CONTRIBUTORS, THEIR CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT'S USE OF THE SUBJECT CONTENTS RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S USE OF THE SUBJECT CONTENTS, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE REPOSITORY OWNERS AND CONTRIBUTORS, THEIR CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW.\n\n# License\n\u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\"\u003e\u003cimg alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-sa/4.0/88x31.png\" /\u003e\u003c/a\u003e\u003cbr /\u003eThis work is licensed under a \u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\"\u003eCreative Commons Attribution-ShareAlike 4.0 International License\u003c/a\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcariboulabs%2Fcariboulite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcariboulabs%2Fcariboulite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcariboulabs%2Fcariboulite/lists"}