kopia lustrzana https://github.com/cariboulabs/cariboulite
readmes update
David Michaeli
rodzic
ceb6d4f679
commit
984a3b3ec8
27
README.md
27
README.md
|
|
@ -1,8 +1,15 @@
|
|||
# CaribouLite
|
||||
CaribouLite is an affordable, educational, open-source SDR 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.
|
||||
CaribouLite 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.
|
||||
|
||||
CaribouLite has been submitted to CrowdSupply and has been pre-launched! [Visit our page](https://www.crowdsupply.com/cariboulabs/cariboulite)
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td><img src="hardware/rev2/pictures/oshwa.png" alt="Open source hardware association certificate"></td>
|
||||
<td>This project has be certified by OSHWA</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td><img src="hardware/rev2/pictures/DSC_1151.jpg" alt="CaribouLite R2" height="200"></td>
|
||||
|
|
@ -13,12 +20,13 @@ CaribouLite has been submitted to CrowdSupply and has been pre-launched! [Visit
|
|||
</table>
|
||||
|
||||
# Getting Started & Installation
|
||||
Use the following steps for successful installation of the CaribouLite on your choice of RPI board
|
||||
Use the following steps to install the CaribouLite on your choice of RPI board
|
||||
1. Mount the CaribouLite on a **un-powered** RPI device using the 40-pin header.
|
||||
2. Power the RPI device, wait for it to finish boot sequence.
|
||||
3. Clone this repository in your choice of directory
|
||||
3. Clone this repository into a local directory of your choise (in this case `~/projects`)
|
||||
```
|
||||
mkdir projects
|
||||
mkdir ~/projects
|
||||
cd ~/projects
|
||||
git clone https://github.com/cariboulabs/cariboulite
|
||||
cd cariboulite
|
||||
```
|
||||
|
|
@ -39,14 +47,11 @@ Following these steps, the RPI has to be rebooted before starting using it as an
|
|||
|
||||
# SMI Interface
|
||||
|
||||
Unlike many other HAT projects, CaribouLite utilizes the <B>SMI</B> (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 ~500Mbit/s 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.
|
||||
Unlike 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.
|
||||
|
||||
The 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 it also provides 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).
|
||||
|
||||
The SMI interface is used as memory interface that pipes the I/Q complex samples from the CaribouLite to the RPI Broadcomm SoC (on RX) and from the Broadcomm SoC to the board (on TX).
|
||||
A single ADC sample contains 13 bit (I) and 13 bit (Q), that are streamed with a maximal sample rate of 4 MSPS from the AT86RF215 IC to an FPGA. The FPGA emulated SMI compliant memory interface for the RPI SoC.
|
||||
Each RF channel (CaribouLite has two of them) requires 4 bytes (samples padded to 32-bit) per sample (and I/Q pair) => 16 MBytes/sec which are 128 MBits/sec. In addition to the 13 bit for each of I/Q, the Tx/Rx streams of data contain flow control and configuration bits. The modem (AT86RF215) IC by Microchip contains two RX I/Q outputs from its ADCs (one for each physical channel - sub-1GHz and 2.4GHz), and a single TX I/Q intput directed to the DACs.
|
||||
The 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`.
|
||||
|
||||
More 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).
|
||||
|
||||
|
||||
<table>
|
||||
|
|
@ -126,7 +131,7 @@ Parameter | Sub-1GHz | Wide Tuning Channel
|
|||
---------------------------|------------------------------|------------------------------------------------------------------
|
||||
Frequency tuner range | 389.5-510 MHz / 779-1020 MHz | 30 MHz - 6 GHz (excluding 2398.5-2400 MHz and 2483.5-2485 MHz)
|
||||
Sample rate (ADC / DAC) | 4 MSPS | 4 MSPS
|
||||
Analog bandwidth (Rx / Tx) | 2 MHz | 2 MHz
|
||||
Analog bandwidth (Rx / Tx) | 2.5 MHz | 2.5 MHz
|
||||
Max Transmit power | 14 dBm | >10 dBm @ 30-2400 MHz, >5 dBm @ 2400-6000 MHz
|
||||
Receive noise figure | <5 dB | <6 dB @ 30-3500 MHz, <8 dB @ 3500-6000 MHz
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
# Overview
|
||||
The SMI interface is used as memory interface that pipes the I/Q complex samples from the CaribouLite to the RPI Broadcomm SoC (on RX) and from the Broadcomm SoC to the board (on TX).
|
||||
A single ADC sample contains 13 bit (I) and 13 bit (Q), that are streamed with a maximal sample rate of 4 MSPS from the AT86RF215 IC to an FPGA. The FPGA emulated SMI compliant memory interface for the RPI SoC.
|
||||
Each RF channel (CaribouLite has two of them) requires 4 bytes (samples padded to 32-bit) per sample (and I/Q pair) => 16 MBytes/sec which are 128 MBits/sec. In addition to the 13 bit for each of I/Q, the Tx/Rx streams of data contain flow control and configuration bits. The modem (AT86RF215) IC by Microchip contains two RX I/Q outputs from its ADCs (one for each physical channel - sub-1GHz and 2.4GHz), and a single TX I/Q intput directed to the DACs.
|
||||
|
||||
# Connections and Description
|
||||
TBD
|
||||
|
||||
# Operation
|
||||
TBD
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
# Overview
|
||||
TBD
|
||||
|
|
@ -1,2 +1,81 @@
|
|||
# The SMI interface Overview
|
||||
TBD
|
||||
# Caribou-SMI API Driver
|
||||
This directory contains a user-mode interface code with the `bcm2835_smi` kernel module.
|
||||
To start working with the interface, some kernel modules need to be probed first.
|
||||
|
||||
By default, CaribouLite boards are pre-programmed to automatically probe the SMI modules on startup. Each CaribouLite contains an EEPROM device that in programmed during production with the updated device tree overlay (for more info [see here](../../../devicetrees/README.md)) file that loads on startup. This device tree "requests" loading the SMI associated kernel modules on startup. So if you have your CaribouLite board mounted on the 40-pin header, the module probing is not necessary.
|
||||
|
||||
To check whether these modules are probed, follow the next command in your Raspberry Pi terminal:
|
||||
```
|
||||
lsmod | grep smi
|
||||
```
|
||||
|
||||
you should be seeing the following output:
|
||||
```
|
||||
TBD TBD
|
||||
```
|
||||
|
||||
If you do not see these modules, please check:
|
||||
1. The CaribouLite is properly mounted and powered.
|
||||
2. The CAribouLite is properly flashed - follow [this link](../../../../docs/flashing/README.md)
|
||||
|
||||
For detailed hardware-related information on the SMI interface, please click [here](../../../../docs/smi/README.md)
|
||||
|
||||
# The API
|
||||
## Initializing and closing the SMI instance
|
||||
|
||||
**Opening** the device and configuring the error-callback-function to be triggered once an error ocurred:
|
||||
```
|
||||
int caribou_smi_init(caribou_smi_st* dev,
|
||||
caribou_smi_error_callback error_cb,
|
||||
void* context);
|
||||
```
|
||||
|
||||
**Closing** the device:
|
||||
```
|
||||
int caribou_smi_close (caribou_smi_st* dev);
|
||||
```
|
||||
|
||||
## Reading and writing into the device
|
||||
|
||||
**Reading** into a buffer with timeout. If the SMI connected device (in this case, CaribouLite) doesn't have enough data to send, this function will wait till the timeout elapses. For non-blocking operation, please set `timeout = 0`
|
||||
```
|
||||
int caribou_smi_timeout_read(caribou_smi_st* dev,
|
||||
caribou_smi_address_en source,
|
||||
char* buffer,
|
||||
int size_of_buf,
|
||||
int timeout_num_millisec);
|
||||
```
|
||||
|
||||
```
|
||||
writing - TBD
|
||||
```
|
||||
|
||||
## Stream operations
|
||||
In most cases, working with file read/write synchronously is not the right choice. If we want an asynchronous operation with events and callbacks, we should setup a stream as follows:
|
||||
```
|
||||
int caribou_smi_setup_stream(caribou_smi_st* dev,
|
||||
caribou_smi_stream_type_en type,
|
||||
caribou_smi_channel_en channel,
|
||||
int batch_length, int num_buffers,
|
||||
caribou_smi_data_callback cb,
|
||||
void* serviced_context);
|
||||
```
|
||||
`batch_length` - is the length of a single buffer to serve (in bytes)
|
||||
`num_buffers` - is the number of batch buffers to allocate - for fluent buffer swapping
|
||||
`cb` - data callback function that is triggered every time a buffer is ready to be served.
|
||||
`serviced_context` - the data "requester" that is being serviced by the I/Q data. In most cases that is a higher layered driver / API.
|
||||
|
||||
Notes: Once the stream is created it is operational **but paused!** to activate it see below.
|
||||
|
||||
|
||||
```
|
||||
int caribou_smi_run_pause_stream (caribou_smi_st* dev, int id, int run);
|
||||
```
|
||||
|
||||
```
|
||||
int caribou_smi_destroy_stream(caribou_smi_st* dev, int id);
|
||||
```
|
||||
|
||||
```
|
||||
char* caribou_smi_get_error_string(caribou_smi_error_en err);
|
||||
```
|
||||
Ładowanie…
Reference in New Issue