From 23a092f4444db40c0433d29132dc10dd6801a824 Mon Sep 17 00:00:00 2001 From: straithe Date: Thu, 20 Oct 2022 18:30:01 -0400 Subject: [PATCH 1/2] Update Opera Cake docs --- docs/source/index.rst | 21 ++- docs/source/opera_cake.rst | 165 +----------------- docs/source/opera_cake_board_addressing.rst | 60 +++++++ docs/source/opera_cake_faq.rst | 13 ++ docs/source/opera_cake_hardware.rst | 18 ++ docs/source/opera_cake_modes_of_operation.rst | 58 ++++++ docs/source/opera_cake_port_configuration.rst | 22 +++ 7 files changed, 195 insertions(+), 162 deletions(-) create mode 100644 docs/source/opera_cake_board_addressing.rst create mode 100644 docs/source/opera_cake_faq.rst create mode 100644 docs/source/opera_cake_hardware.rst create mode 100644 docs/source/opera_cake_modes_of_operation.rst create mode 100644 docs/source/opera_cake_port_configuration.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index b5d0e378..f2c06d49 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,11 +4,9 @@ Welcome to HackRF's documentation! .. toctree:: :maxdepth: 2 - :caption: User Documentation + :caption: HackRF User Documentation hackrf_one - jawbreaker - opera_cake faq troubleshooting getting_help @@ -46,3 +44,20 @@ Welcome to HackRF's documentation! expansion_interface hardware_triggering rf_shield_installation + +.. toctree:: + :maxdepth: 2 + :caption: Opera Cake Documentation + + opera_cake + opera_cake_faq + opera_cake_hardware + opera_cake_board_addressing + opera_cake_port_configuration + opera_cake_modes_of_operation + +.. toctree:: + :maxdepth: 2 + :caption: Jawbreaker Documentation + + jawbreaker \ No newline at end of file diff --git a/docs/source/opera_cake.rst b/docs/source/opera_cake.rst index b3ac0b72..f1c70f58 100644 --- a/docs/source/opera_cake.rst +++ b/docs/source/opera_cake.rst @@ -1,167 +1,14 @@ -================================================ +========== Opera Cake -================================================ +========== .. image:: ../images/operacake.jpeg :alt: Opera Cake Opera Cake is an antenna switching add-on board for HackRF One. Consisting of two 1x4 switches, Opera Cake also has a cross-over switch that permits operation as a 1x8 switch. Up to eight Opera Cakes may be stacked onto a single HackRF One provided that each Opera Cake is configured with a different board address. +Opera Cake can be used as a 1x8 switch to connect your HackRF One to a variety of antennas at once, such as a long wire antenna for HF bands, a discone for VHF and UHF, a dipole for 2.4 GHz, and a dish for a satellite band. Once connected to your Opera Cake you can switch between all of your antennas in software instead of making physical hardware swaps. + +When set up as a pair of 1x4 switches you could use Opera Cake as a switched filter bank. To do this, connect port A1 to B1, A2 to B2, A3 to B3, and A4 to B4 through physical SMA filters and cables of your choosing. This setup allows you to change your transmit or receive to be through the filter of your choosing without having to reconnect hardware every time you would like to use a different filter. + Opera Cake is configured with the ``hackrf_operacake`` command-line tool. - - -Using Opera Cake -~~~~~~~~~~~~~~~~ - -Banks -^^^^^ - -Opera Cake's ports are grouped in two banks (or "sides"), one on each end of the board. Bank A consists of ports A0 through A4 while bank B consists of ports B0 through B4. - -Ports -^^^^^ - -Opera Cake has two primary ports, A0 and B0, each of which can be switched to any of eight secondary ports, A1-A4 and B1-B4. Each primary port is always connected to one secondary port. By default, A0 is connected to A1, and B0 is connected to B1. It is not possible to connect both primary ports to secondary ports in the same bank at the same time. - -Port connections may be configured manually. For example, to connect A0 to A2 and B0 to B3: - -.. code-block:: sh - - hackrf_operacake -a A2 -b B3 - -To connect A0 to B2 and B0 to A4: - -.. code-block:: sh - - hackrf_operacake -a B2 -b A4 - -If only one primary port is configured, the other primary port will be connected to the first secondary port on the opposite side. For example, after the next two commands B0 will be connected to A1: - -.. code-block:: sh - - hackrf_operacake -a A2 -b B3 - hackrf_operacake -a B2 - -LEDs -^^^^ - -Port selections are indicated by LEDs next to each port's connector. Port A0 and the secondary port connected to A0 are indicated with a green LED. Port B0 and the secondary port connected to B0 are indicated with a yellow LED. - -Board Address -^^^^^^^^^^^^^ - -Each Opera Cake has a numeric address set by optional jumpers installed on header P1. The default address (without jumpers) is 0. The ``--list`` or ``-l`` option can be used to list the address(es) of one or more Opera Cakes installed on a HackRF One: - -.. code-block:: sh - - hackrf_operacake -l - -The address may be set to any number from 0 to 7 by installing jumpers across the A0, A1, and/or A2 pins of header P1. - -.. list-table:: - :header-rows: 1 - :widths: 1 1 1 1 - - * - Address - - A2 Jumper - - A1 Jumper - - A0 Jumper - * - 0 - - No - - No - - No - * - 1 - - No - - No - - Yes - * - 2 - - No - - Yes - - No - * - 3 - - No - - Yes - - Yes - * - 4 - - Yes - - No - - No - * - 5 - - Yes - - No - - Yes - * - 6 - - Yes - - Yes - - No - * - 7 - - Yes - - Yes - - Yes - -When configuring an Opera Cake, the address may be specified with the ``--address`` or ``-o`` option: - -.. code-block:: sh - - hackrf_operacake -o 1 -a A1 -b B2 - -If the address is unspecified, 0 is assumed. It is only necessary to specify the address if the address has been changed with the addition of jumpers, typically required only if multiple Opera Cakes are stacked onto a single HackRF One. - - -Modes of Operation -~~~~~~~~~~~~~~~~~~ - -Opera Cake supports three modes of operation: ``manual``, ``frequency``, and ``time``. The operating mode can be set with the ``--mode`` or ``-m`` option, and the active operating mode is displayed with the ``--list`` or ``-l`` option. - -Manual Mode -^^^^^^^^^^^ - -The default mode of operation is ``manual``. In manual mode, fixed port connections are configured with the ``-a`` and ``-b`` options as in the port configuration examples above. If the operating mode has been changed, it can be changed back to manual mode with: - -.. code-block:: sh - - hackrf_operacake -m manual - -Frequency Mode -^^^^^^^^^^^^^^ - -In frequency mode, the A0 port connection switches automatically whenever the HackRF is tuned to a different frequency. This is useful when antennas for different frequency bands are connected to various ports. - -The bands are specified in priority order. The final band specified will be used for frequencies not covered by the other bands specified. - -To assign frequency bands to ports you must use the ``-f `` option for each band, with the minimum and maximum frequencies specified in MHz. For example, to use port A1 for 100 MHz to 600 MHz, A3 for 600 MHz to 1200 MHz, and B2 for 0 MHz to 4 GHz: - -.. code-block:: sh - - hackrf_operacake -m frequency -f A1:100:600 -f A3:600:1200 -f B2:0:4000 - -If tuning to precisely 600 MHz, A1 will be used as it is listed first. Tuning to any frequency over 4 GHz will use B2 as it is the last listed and therefore the default port. - -Only the A0 port connection is specified in frequency mode. Whenever the A0 connection is switched, the B0 connection is also switched to the secondary port mirroring A0's secondary port. For example, when A0 switches to B2, B0 is switched to A2. - -Once configured, an Opera Cake will remain in frequency mode until the mode is reconfigured or until the HackRF One is reset. You can pre-configure the Opera Cake in frequency mode, and the automatic switching will continue to work while using other software. - -Although multiple Opera Cakes on a single HackRF One may be set to frequency mode at the same time, they share a single switching plan. This can be useful, for example, for a filter bank consisting of eight filters. - -Time Mode -^^^^^^^^^ - -In time mode, the A0 port connection switches automatically over time, counted in units of the sample period. This is useful for experimentation with pseudo-doppler direction finding. - -To cycle through four ports, one port every 1000 samples: - -.. code-block:: none - - hackrf_operacake -m time -t A1:1000 -t A2:1000 -t A3:1000 -t A4:1000 - -When the duration on multiple ports is the same, the ``-w`` option can be used to set the default dwell time: - -.. code-block:: none - - hackrf_operacake --mode time -w 1000 -t A1 -t A2 -t A3 -t A4 - -Only the A0 port connection is specified in time mode. Whenever the A0 connection is switched, the B0 connection is switched to the secondary port mirroring A0's secondary port. For example, when A0 switches to B2, B0 is switched to A2. - -Once configured, an Opera Cake will remain in time mode until the mode is reconfigured or until the HackRF One is reset. You can pre-configure the Opera Cake in time mode, and the automatic switching will continue to work while using other software. - -Although multiple Opera Cakes on a single HackRF One may be set to time mode at the same time, they share a single switching plan. diff --git a/docs/source/opera_cake_board_addressing.rst b/docs/source/opera_cake_board_addressing.rst new file mode 100644 index 00000000..487438ab --- /dev/null +++ b/docs/source/opera_cake_board_addressing.rst @@ -0,0 +1,60 @@ +================ +Board Addressing +================ + +Each Opera Cake has a numeric address set by optional jumpers installed on header P1. The default address (without jumpers) is 0. The ``--list`` or ``-l`` option can be used to list the address(es) of one or more Opera Cakes installed on a HackRF One: + +.. code-block:: sh + + hackrf_operacake -l + +The address may be set to any number from 0 to 7 by installing jumpers across the A0, A1, and/or A2 pins of header P1. + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 1 + + * - Address + - A2 Jumper + - A1 Jumper + - A0 Jumper + * - 0 + - No + - No + - No + * - 1 + - No + - No + - Yes + * - 2 + - No + - Yes + - No + * - 3 + - No + - Yes + - Yes + * - 4 + - Yes + - No + - No + * - 5 + - Yes + - No + - Yes + * - 6 + - Yes + - Yes + - No + * - 7 + - Yes + - Yes + - Yes + +When configuring an Opera Cake, the address may be specified with the ``--address`` or ``-o`` option: + +.. code-block:: sh + + hackrf_operacake -o 1 -a A1 -b B2 + +If the address is unspecified, 0 is assumed. It is only necessary to specify the address if the address has been changed with the addition of jumpers, typically required only if multiple Opera Cakes are stacked onto a single HackRF One. diff --git a/docs/source/opera_cake_faq.rst b/docs/source/opera_cake_faq.rst new file mode 100644 index 00000000..607ae921 --- /dev/null +++ b/docs/source/opera_cake_faq.rst @@ -0,0 +1,13 @@ +===================================== +Frequently Asked Questions +===================================== + +Why the name 'Opera Cake'? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Internally at Great Scott Gadgets, HackRF related boards are code named with a candy or confection name. The Opera Cake code name was fun enough that we didn't change from it when we released the project. + +When was Opera Cake first for sale? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Great Scott Gadgets first released Opera Cake for sale in 2022. The open source project for Opera Cake has been available since 2016 from Great Scott Gadgets. \ No newline at end of file diff --git a/docs/source/opera_cake_hardware.rst b/docs/source/opera_cake_hardware.rst new file mode 100644 index 00000000..deba37db --- /dev/null +++ b/docs/source/opera_cake_hardware.rst @@ -0,0 +1,18 @@ +======== +Hardware +======== + +Banks +~~~~~ + +The ports on Opera Cake are grouped in two banks (or "sides"), one on each end of the board. Bank A consists of ports A0 through A4 while bank B consists of ports B0 through B4. + +Ports +~~~~~ + +Opera Cake has two primary ports, A0 and B0, each of which can be switched to any of eight secondary ports, A1-A4 and B1-B4. Each primary port is always connected to one secondary port. By default, A0 is connected to A1, and B0 is connected to B1. It is not possible to connect both primary ports to secondary ports in the same bank at the same time. + +LEDs +~~~~ + +Port selections are indicated by LEDs next to each port's connector. Port A0 and the secondary port connected to A0 are indicated with a green LED. Port B0 and the secondary port connected to B0 are indicated with a yellow LED. \ No newline at end of file diff --git a/docs/source/opera_cake_modes_of_operation.rst b/docs/source/opera_cake_modes_of_operation.rst new file mode 100644 index 00000000..a73349e5 --- /dev/null +++ b/docs/source/opera_cake_modes_of_operation.rst @@ -0,0 +1,58 @@ +================== +Modes of Operation +================== + +Opera Cake supports three modes of operation: ``manual``, ``frequency``, and ``time``. The operating mode can be set with the ``--mode`` or ``-m`` option, and the active operating mode is displayed with the ``--list`` or ``-l`` option. + +Manual Mode +~~~~~~~~~~~ + +The default mode of operation is ``manual``. In manual mode, fixed port connections are configured with the ``-a`` and ``-b`` options as in the port configuration examples above. If the operating mode has been changed, it can be changed back to manual mode with: + +.. code-block:: sh + + hackrf_operacake -m manual + +Frequency Mode +~~~~~~~~~~~~~~ + +In frequency mode, the A0 port connection switches automatically whenever the HackRF is tuned to a different frequency. This is useful when antennas for different frequency bands are connected to various ports. + +The bands are specified in priority order. The final band specified will be used for frequencies not covered by the other bands specified. + +To assign frequency bands to ports you must use the ``-f `` option for each band, with the minimum and maximum frequencies specified in MHz. For example, to use port A1 for 100 MHz to 600 MHz, A3 for 600 MHz to 1200 MHz, and B2 for 0 MHz to 4 GHz: + +.. code-block:: sh + + hackrf_operacake -m frequency -f A1:100:600 -f A3:600:1200 -f B2:0:4000 + +If tuning to precisely 600 MHz, A1 will be used as it is listed first. Tuning to any frequency over 4 GHz will use B2 as it is the last listed and therefore the default port. + +Only the A0 port connection is specified in frequency mode. Whenever the A0 connection is switched, the B0 connection is also switched to the secondary port mirroring A0's secondary port. For example, when A0 switches to B2, B0 is switched to A2. + +Once configured, an Opera Cake will remain in frequency mode until the mode is reconfigured or until the HackRF One is reset. You can pre-configure the Opera Cake in frequency mode, and the automatic switching will continue to work while using other software. + +Although multiple Opera Cakes on a single HackRF One may be set to frequency mode at the same time, they share a single switching plan. This can be useful, for example, for a filter bank consisting of eight filters. + +Time Mode +~~~~~~~~~ + +In time mode, the A0 port connection switches automatically over time, counted in units of the sample period. This is useful for experimentation with pseudo-doppler direction finding. + +To cycle through four ports, one port every 1000 samples: + +.. code-block:: none + + hackrf_operacake -m time -t A1:1000 -t A2:1000 -t A3:1000 -t A4:1000 + +When the duration on multiple ports is the same, the ``-w`` option can be used to set the default dwell time: + +.. code-block:: none + + hackrf_operacake --mode time -w 1000 -t A1 -t A2 -t A3 -t A4 + +Only the A0 port connection is specified in time mode. Whenever the A0 connection is switched, the B0 connection is switched to the secondary port mirroring A0's secondary port. For example, when A0 switches to B2, B0 is switched to A2. + +Once configured, an Opera Cake will remain in time mode until the mode is reconfigured or until the HackRF One is reset. You can pre-configure the Opera Cake in time mode, and the automatic switching will continue to work while using other software. + +Although multiple Opera Cakes on a single HackRF One may be set to time mode at the same time, they share a single switching plan. diff --git a/docs/source/opera_cake_port_configuration.rst b/docs/source/opera_cake_port_configuration.rst new file mode 100644 index 00000000..8ce36016 --- /dev/null +++ b/docs/source/opera_cake_port_configuration.rst @@ -0,0 +1,22 @@ +=================== +Port Configurations +=================== + +Port connections may be configured manually. For example, to connect A0 to A2 and B0 to B3: + +.. code-block:: sh + + hackrf_operacake -a A2 -b B3 + +To connect A0 to B2 and B0 to A4: + +.. code-block:: sh + + hackrf_operacake -a B2 -b A4 + +If only one primary port is configured, the other primary port will be connected to the first secondary port on the opposite side. For example, after the next two commands B0 will be connected to A1: + +.. code-block:: sh + + hackrf_operacake -a A2 -b B3 + hackrf_operacake -a B2 From e1e95b0dc9348824017bb42f48741eaed327b44e Mon Sep 17 00:00:00 2001 From: straithe Date: Fri, 28 Oct 2022 15:37:40 -0400 Subject: [PATCH 2/2] docs: update documentaiton based on PR changes requested --- docs/source/index.rst | 10 +++------- docs/source/opera_cake_modes_of_operation.rst | 2 +- docs/source/opera_cake_port_configuration.rst | 2 ++ 3 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index f2c06d49..707647b1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,9 +4,10 @@ Welcome to HackRF's documentation! .. toctree:: :maxdepth: 2 - :caption: HackRF User Documentation + :caption: User Documentation hackrf_one + jawbreaker faq troubleshooting getting_help @@ -55,9 +56,4 @@ Welcome to HackRF's documentation! opera_cake_board_addressing opera_cake_port_configuration opera_cake_modes_of_operation - -.. toctree:: - :maxdepth: 2 - :caption: Jawbreaker Documentation - - jawbreaker \ No newline at end of file + \ No newline at end of file diff --git a/docs/source/opera_cake_modes_of_operation.rst b/docs/source/opera_cake_modes_of_operation.rst index a73349e5..3af826e8 100644 --- a/docs/source/opera_cake_modes_of_operation.rst +++ b/docs/source/opera_cake_modes_of_operation.rst @@ -7,7 +7,7 @@ Opera Cake supports three modes of operation: ``manual``, ``frequency``, and ``t Manual Mode ~~~~~~~~~~~ -The default mode of operation is ``manual``. In manual mode, fixed port connections are configured with the ``-a`` and ``-b`` options as in the port configuration examples above. If the operating mode has been changed, it can be changed back to manual mode with: +The default mode of operation is ``manual``. In manual mode, fixed port connections are configured with the ``-a`` and ``-b`` options as in the :ref:`port configuration examples `. If the operating mode has been changed, it can be changed back to manual mode with: .. code-block:: sh diff --git a/docs/source/opera_cake_port_configuration.rst b/docs/source/opera_cake_port_configuration.rst index 8ce36016..9a7d6b48 100644 --- a/docs/source/opera_cake_port_configuration.rst +++ b/docs/source/opera_cake_port_configuration.rst @@ -1,3 +1,5 @@ +.. _portconfiguration: + =================== Port Configurations ===================