Skip to content

P
Programmable RF Attenuator
Commit 6fcb20cc authored by Dimitris Lampridis's avatar Dimitris Lampridis
Browse files
Options

Merge branch '3-document-and-publish-the-programming-and-testing-procedure' into 'master' 

Resolve "Document and publish the programming and testing procedure"

Closes #3

See merge request be-cem-edl/fec/hardware-modules/rf-att-4cha!2
parents 81b13d72 9538cdfb
Pipeline #4463 failed
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1045 additions and 38 deletions
.gitlab-ci.yml 0 → 100644
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
variables:
EDL_CI_DOC_SRC_PATH: 'doc'
EDL_CI_DOC_DST_PATH: $CI_PROJECT_DIR/$EDL_CI_EOS_OUTPUT_DIR/doc/user_manual
include:
- project: 'be-cem-edl/evergreen/gitlab-ci'
ref: master
file: 'edl-gitlab-ci.yml'
build_software:
stage: build
image: gitlab-registry.cern.ch/be-cem-edl/evergreen/gitlab-ci/build-fec-sw:latest
interruptible: true
variables:
_DOXYGEN_DEST: $CI_PROJECT_DIR/$EDL_CI_EOS_OUTPUT_DIR/doc/developer_manual
before_script:
- yum install -q -y libftdi-devel systemd-devel which doxygen
script:
- make -C software
- mkdir -p $_DOXYGEN_DEST
- cp -r software/lib/html/* $_DOXYGEN_DEST/
artifacts:
name: "$CI_COMMIT_TIMESTAMP-$CI_JOB_ID-$CI_COMMIT_SHORT_SHA-doxygen"
paths:
- $_DOXYGEN_DEST/*
.reuse/dep5 0 → 100644
View file @ 6fcb20cc
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: USB programmable RF attenuator
Upstream-Contact: Dimitris Lampridis <dimitris.lampridis@cern.ch>
Source: https://ohwr.org/project/rf-att-4cha
Files: hardware/*
Copyright:2020 CERN (home.cern)
License: CERN-OHL-W-2.0
LICENSES/CC-BY-SA-4.0.txt 0 → 100644
View file @ 6fcb20cc
This diff is collapsed.
LICENSES/CERN-OHL-W-2.0.txt 0 → 100644
View file @ 6fcb20cc
This diff is collapsed.
LICENSES/LGPL-2.1-or-later.txt 0 → 100644
View file @ 6fcb20cc
This diff is collapsed.
README.md 0 → 100644
View file @ 6fcb20cc
<!--
SPDX-FileCopyrightText: 2022 CERN
SPDX-License-Identifier: CC-BY-SA-4.0+
-->
<!--shared-with-mkdocs-start-->
# USB Programmable RF Attenuator
Programmable attenuator of RF signals with very high voltage range (50mV – 1000V)
for protecting digitizers against damage by high voltage signals. Four
channels with SMA connectors; Three attenuation values: 0, -20, -40 dB;
Bandwidth: DC – 2 GHz.
19-inch rack form factor and controlled and powered over USB.
<!--shared-with-mkdocs-end-->
For more information, please refer to the [published documentation](https://be-cem-edl.web.cern.ch/rf-att-4cha).
doc/.gitignore 0 → 100644
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2022 CERN (home.cern)
#
# SPDX-License-Identifier: CC-BY-SA-4.0+
site/
temp_dir/
# temporary files
*~
doc/docs/factory-testing-procedure.md 0 → 100644
View file @ 6fcb20cc
<!--
SPDX-FileCopyrightText: 2023 CERN (home.cern)
SPDX-License-Identifier: CC-BY-SA-4.0+
-->
# Factory Testing Procedure
Each device produced contains an empty EEPROM that needs to be programmed with
the following information:
- device VID:PID
- product description
- serial number
- default power-on settings
Furthermore, each new device needs to be tested to verify that it is properly
functioning within specifications.
## EEPROM programming
**Preparation**
- Get a Linux computer and build and install the latest release of the
attenuator library and test program (if not already available).
- Connect the Device Under Test (DUT) to the computer via USB.
- Make sure that the FTDI device driver which comes by default with most Linux
distributions is not loaded after plugging in the DUT. You can use the `lsmod`
command and look for the `ftdi_sio` driver in the output. If the driver is
loaded, you must remove it using the `modprobe` command:
```
$ lsmod | grep -c ftdi
1
$ sudo modprobe -r ftdi_sio
$ lsmod | grep ftdi
0
```
!!! hint
Every time you plug a new unprogrammed DUT, the operating system will try to
reload the `ftdi_sio` driver. To prevent this behaviour, you can blacklist
the driver like this:
```
echo "blacklist ftdi_sio" > /etc/modprobe.d/ftdi-blacklist.conf
```
If you are working in a non-persistent filesystem (as in the case of a CERN
Front-End Computer), you will need to repeat this every time you reboot the
computer.
**Procedure**
!!! warning
Be sure to properly identify and select your USB device below.
The programming tool will refuse to work if the VID:PID is not
matched but, if your computer has any other USB peripherals
using an FTDI chip (quite common, especially for USB to serial
converters), you might accidentally program another USB device
and brick it.
1. Connect the DUT to the computer via USB and check that the power LED is ON.
2. Use the `lsusb` command and look for the DUT, if it has never been programmed
it will be listed with the default FTDI VID:PID (`0403:6010`), otherwise it
will have the CERN one (`1556:0443`). Note down the `Bus` and `Device`
number.
3. Run the test program (`oattnusbtest`) and use the `eeprom_program` command
while providing the `Bus` and `Device` numbers from the previous steps as
parameters. You will be also asked in a separate prompt to input the serial
number to be programmed into the device. The result should look like this:
```
oatt> eeprom_program 1 14
Please provide the serial number to program: HCCAIAD000-CR000038
WARNING: about to erase and program the EEPROM with new serial number
[HCCAIAD000-CR000038] into dev with old serial: [EMPTY] at
busdev: 1/14, busport: 1-3.2.4
are you sure? (yes/N) yes
backing up EEPROM into /tmp/eeprom_dump-1682680819412215.bin
backing up EEPROM into /tmp/eeprom_dump-1682680819416644.bin
VID: 0x1556
PID: 0x0443
Release: 0x0700
Bus Powered: 100 mA
Manufacturer: CERN
Product: OASIS RF Attenuator
Serial: HCCAIAD000-CR000038
Checksum : c928
Attached EEPROM: 93x46
PNP: 1
Channel A has Mode FIFO VCP
Channel B has Mode FIFO VCP
AL has 4 mA drive
AH has 4 mA drive
BL has 4 mA drive
BH has 4 mA drive
successful EEPROM write, resetting USB device
new serial recorded!
quitting, please restart the test program
```
4. Following the EEPROM programming, the test program will automatically terminate.
5. Unplug and replug the USB cable of the DUT to perform a power cycle.
6. Verify that all four channels power up at -40dB attenuation (a quick flicker
during power up is to be expected).
!!! hint
If you have a barcode sticker ready for the DUT, you can use a barcode scanner
to pass it on to the test program during programming, to avoid any
copying-by-hand mistakes.
## Testing
**Preparation**
- You will need the same computer setup that you used for programming the
EEPROM and the DUT should be already [programmed](#eeprom-programming).
- Get a vector/scalar Network Analyzer (NA) which works at least up to 2 GHz.
- Set the NA to 0dB ref level, S21 measurement, 2 GHz bandwidth, high RBW/VBW
(so that sweeps take short time).
- Connect two SMA cables to the NA ports.
**Procedure**
1. Connect the DUT to the computer via USB and check that the power LED is ON.
2. Run the test program and try detecting the DUT using the `ls` command. You
should see an output like this:
```
oatt> ls
0: l:0 serial:HCCAIAD000-CR000038 busdev:1/14 busport:1-3.2.4
```
3. Request access to the DUT via the `open` command. You should see an output
like this:
```
oatt> open
current device: serial HCCAIAD000-CR000038, fd 1, 4 channels
```
4. Connect the NA to the input and output of DUT channel 1.
5. Set the attenuation of channel 1 to 0dB.
```
oatt> set_attn 1 0dB
```
6. Verify that the 0dB LED of channel 1 is on.
7. Look at the screen of the NA to see if it's around 0 dB (±3dB) in the whole
bandwidth (up to 2 GHz). Close to the limit of 2 GHz it is ok if it goes a
bit beyond ±3dB. However, look out for sudden spikes/dips (in the order of
±6dB or more) across the whole measured bandwidth.
8. Repeat steps 5 to 7 for -20dB and -40dB attenuation levels.
9. Repeat steps 4 to 8 for DUT channels 2, 3 and 4.
10. Close the access to the DUT via the `close` command.
11. Disconnect the DUT from the computer.
!!! hint
The prompt of the test program keeps a history of previous commands. You can use
the up/down arrows to repeat previous commands.
doc/docs/index.md 0 → 100644
View file @ 6fcb20cc
<!--
SPDX-FileCopyrightText: 2023 CERN (home.cern)
SPDX-License-Identifier: CC-BY-SA-4.0+
-->
{%
include-markdown "root-readme-link.md"
start="<!--shared-with-mkdocs-start-->"
end="<!--shared-with-mkdocs-end-->"
%}
# Specification
- 19-inch, 1U form factor
- 4 channels with SMA connectors
- 3 attenuation values: 0, -20 dB, -40 dB
- Bandwidth: DC – 2 GHz
- Insertion loss: -1.5 dB
- Maximum power dissipation: 1 W (in a 1 ms-long pulse train with 1 J total energy)
- Default attenuation: -40 dB
- Additional protection for the scope by an external RF limiter
- USB input for attenuation selection (USB VID/PID: 1556/0443) and power supply (powered from the USB host)
- Reliability: 10 million mechanical cycles
- 4 indicator LEDs: 3 for showing the current attenuation (per channel)
- Readout of current attenuation
doc/docs/root-readme-link.md 0 → 120000
View file @ 6fcb20cc
../../README.md
\ No newline at end of file
doc/mkdocs.yml 0 → 100644
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: CC-BY-SA-4.0+
site_name: USB Programmable RF Attenuator
repo_url: https://gitlab.cern.ch/be-cem-edl/fec/hardware-modules/rf-att-4cha
repo_name: source repository
copyright: Copyright &copy; 2023 CERN (home.cern)
theme:
name: material
palette:
# Palette toggle for light mode
- scheme: default
toggle:
icon: fontawesome/regular/lightbulb
name: Switch to dark mode
# Palette toggle for dark mode
- scheme: slate
toggle:
icon: fontawesome/solid/lightbulb
name: Switch to light mode
features:
- navigation.instant
plugins:
- search
- git-revision-date-localized:
fallback_to_build_date: true
enable_creation_date: true
type: date
- include-markdown
markdown_extensions:
- admonition
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.superfences
extra:
generator: false
# Page tree
nav:
- Overview: index.md
- factory-testing-procedure.md
doc/requirements.txt 0 → 100644
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: CC-BY-SA-4.0+
mkdocs
mkdocs-material
mkdocs-git-revision-date-localized-plugin
mkdocs-include-markdown-plugin
software/.gitignore deleted 100644 → 0
View file @ 81b13d72
test
*.o
*.a
*.so
html/
testprog
software/Makefile
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
all clean:
make -C lib $@
software/lib/.gitignore 0 → 100644
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
*.o
*.a
*.so
html/
software/lib/Makefile
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
-include Makefile.ftdi
OBJS = $(LIBNAME).o usb-enum.o eeprom.o
......
software/lib/Makefile.ftdi
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
#
# intra2net does not seem to settle into any side of this
# dilemma, so we have to decide for them, see
......
software/lib/Makefile.install
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
VERSION = $(shell git describe --dirty --tags --long)
OATTN_ROOT = /acc/local/L867/drv/$(NAME)
INSTALL_ROOT = $(OATTN_ROOT)/$(VERSION)
......
software/lib/eeprom.c
View file @ 6fcb20cc
/*
* SPDX-FileCopyrightText: 2023 CERN (home.cern)
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* @file eeprom.c
* @brief Library part that takes care of EEPROM serial number
......
software/lib/liboattnusb-i.h
View file @ 6fcb20cc
/*
* SPDX-FileCopyrightText: 2023 CERN (home.cern)
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* @file liboattnusb-i.h
*
* @brief OASIS USB Attenuator driver library internal definitions
*
* Copyright (c) 2018 CERN
* @author Tomasz Włostowski <tomasz.wlostowski@cern.ch>
* @author Juan David Gonzalez Cobas <dcobas@cern.ch>
*
* @section license_sec License
* Released under the GPL v2. (and only v2, not any later version)
*/
#ifndef __LIBOATTNUSB_I_H
#define __LIBOATTNUSB_I_H
......
software/lib/liboattnusb.c
View file @ 6fcb20cc
/*
* SPDX-FileCopyrightText: 2023 CERN (home.cern)
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* @file liboattnusb.c
* @brief Library file for the msatt driver
* @brief Library file for the oattnusb driver
* @author Tomasz Włostowski
* @date October 17th 2018
*/
......
software/lib/liboattnusb.h
View file @ 6fcb20cc
/*
* SPDX-FileCopyrightText: 2023 CERN (home.cern)
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* @file liboattnusb.h
*
* @brief OASIS USB Attenuator driver library interface
*
* This file describes the external interface to the OASIS USB Attenuator
* driver and provides the definitios for proper communication
* driver and provides the definitions for proper communication
* with the device
*
* Copyright (c) 2018 CERN
* @author Tomasz Włostowski <tomasz.wlostowski@cern.ch>
*
* @section license_sec License
* Released under the GPL v2. (and only v2, not any later version)
*/
#ifndef __LIBOATTNUSB_H
#define __LIBOATTNUSB_H
......@@ -27,22 +27,22 @@ extern "C" {
* \section intro_sec Introduction
*
* To be able to use the library API, you just need to include the
* .liboattnusb.h header file. Linkage requires the flag
* liboattnusb.h header file. Linkage requires the flag
* `-loattnusb` and, in addition, `-lftdi1 -ludev`, as these are
* used by the basic library. To wit:
*
* gcc -o test test.c \
* -L /acc/local/L867/drv/oattn/1.0/lib \
* -I/acc/local/L867/drv/oattn/1.0/include \
* -L <install_path>/lib \
* -I<install_path>/include \
* -loattnusb -lftdi1 -ludev
*
* In case the static version of the library is preferred, a more
* contorted incantation than the above may be required to
* the static library version in a foolproof manner:
* contorted incantation than the above may be required to link to
* the static library in a foolproof manner:
*
* gcc -o test test.c \
* -L /acc/local/L867/drv/oattn/1.0/lib \
* -I/acc/local/L867/drv/oattn/1.0/include \
* -L <install_path>/lib \
* -I<install_path>/include \
* -lftdi1 -ludev \
* -Wl,--push-state,-static \
* -loattnusb \
......@@ -66,7 +66,7 @@ enum oattnusb_value_enum {
};
/**
* @brief Open a msatt device by LUN (not implemented)
* @brief Open a device by LUN (not implemented)
*
* A board is selected by lun, and a handle is returned for further
* reference to it.
......@@ -78,7 +78,7 @@ enum oattnusb_value_enum {
int oattnusb_open(int lun);
/**
* @brief Open a msatt device
* @brief Open a device
*
* Open OASIS USB attenuator with given serial number.
*
......@@ -123,15 +123,15 @@ enum oattnusb_value_enum oattnusb_get_relay(int fd, int channel);
int oattnusb_set_relay(int fd, int channel, enum oattnusb_value_enum val);
/**
* @brief Gets the number of channels (2 or 4)
* @brief Gets the number of channels
*
* @param fd Device handle identifying board
*
* @return -1 on fail, 2 for MSATTN2 and 4 for MSATTN4
* @return OATTNUSB_NUM_CHANNELS
*/
int oattnusb_get_nchannels(int fd);
/* libmsatt version string */
/* liboattnusb version string */
extern const char * const liboattnusb_version_s;
#ifdef __cplusplus
}
......
software/lib/oattn.doxy
View file @ 6fcb20cc
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
QUIET = YES
WARN_IF_UNDOCUMENTED = NO
GENERATE_LATEX = NO
......
software/lib/oattnusbtest
View file @ 6fcb20cc
#!/usr/bin/env python3
# SPDX-FileCopyrightText: 2023 CERN (home.cern)
#
# SPDX-License-Identifier: LGPL-2.1-or-later
# vim: et ts=8 sw=4 sts=4 ai
import cmd
......
software/lib/usb-enum.c
View file @ 6fcb20cc
/*
* SPDX-FileCopyrightText: 2023 CERN (home.cern)
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* @file usb-enum.c
* @brief OASIS USB Attenuator driver library interface
*/
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
......
software/lib/usb-enum.h
View file @ 6fcb20cc
/*
* SPDX-FileCopyrightText: 2023 CERN (home.cern)
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
/**
* @file usb-enum.h
*
* @brief OASIS USB Attenuator driver library interface
*
* This file describes the external interface to the OASIS USB Attenuator
* driver and provides the definitios for proper communication
* driver and provides the definitions for proper communication
* with the device
*
* Copyright (c) 2021 CERN
* @author David Cobas <dcobas AT cern.ch>
*
* Released under the GPL v2. (and only v2, not any later version)
*/
/**
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment