stabilizer - use Hydra builds, remove mentions of the old version

Signed-off-by: Egor Savkin <es@m-labs.hk>

README.md

@@ -33,7 +33,9 @@ Tips for adding hardware instructions:
    for images with transparent background)
 3. Add link to the new chapter to the `src/SUMMARY.md`
 4. Do not forget to tell about all hidden/non-obvious obstacles and pitfalls
-5. Add testing steps, even the "obvious" ones
-6. Add JSON sample if needed
-7. Add hardware setup (e.g. pins, switches) steps if needed
-8. View changed and added pages with `mdbook build` (see building instructions above)
+5. Avoid using uncommon, complex, or hard-to-understand words, phrases, or grammar (e.g., ❌constituent -> ✔️component).
+   Keep in mind that these guides may be used by people with different backgrounds and levels of English proficiency.
+6. Add testing steps, even the "obvious" ones
+7. Add JSON sample if needed
+8. Add hardware setup (e.g. pins, switches) steps if needed
+9. View changed and added pages with `mdbook build` (see building instructions above)

flake.lock

@@ -2,16 +2,16 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1697851979,
-        "narHash": "sha256-lJ8k4qkkwdvi+t/Xc6Fn74kUuobpu9ynPGxNZR6OwoA=",
+        "lastModified": 1710695816,
+        "narHash": "sha256-3Eh7fhEID17pv9ZxrPwCLfqXnYP006RKzSs0JptsN84=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "5550a85a087c04ddcace7f892b0bdc9d8bb080c8",
+        "rev": "614b4613980a522ba49f0d194531beddbb7220d3",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-23.05",
+        "ref": "nixos-23.11",
         "repo": "nixpkgs",
         "type": "github"
       }

flake.nix

@@ -1,7 +1,7 @@
 {
     description = "Sinara assembly and test instructions";
 
-    inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-23.05;
+    inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-23.11;
 
     outputs = { self, nixpkgs }:
 

src/SUMMARY.md

@@ -20,6 +20,7 @@
   - [Sinara 8451 Thermostat](./hw/thermostat.md)
   - [Sinara 2245 LVDS DIO](./hw/lvds_dio.md)
 - [Software/Support](./sw_sup/software_support.md)
+  - [Starting with ARTIQ](./sw_sup/artiq_start.md)
   - [Building legacy firmware](./sw_sup/artiq_legacy.md)
   - [Networking](./sw_sup/networking.md)
   - [DRTIO](./sw_sup/drtio.md)

src/hw/bnc_sma_ttl.md

@@ -13,8 +13,8 @@
   "hw_rev": "vX.Y", // optional
   "ports": [<port num>],
   "edge_counter": <bool>,
-  "bank_direction_low": "input",
-  "bank_direction_high": "output"
+  "bank_direction_low": "input", // or "output"
+  "bank_direction_high": "output" // or "input"
 }
 ```
 

src/hw/clocker.md

@@ -4,20 +4,11 @@
 
 ## JSON
 
-Put the `ext_ref_frequency` field into the JSON description if the Kasli is going to use an external frequency:
+Not present in the JSON.
 
-```json
-{
-  "hw_rev": "<hw rev>",
-  "base": "<base>",
-  ...
-  "ext_ref_frequency": <freq in Hz>,
-  ...
-  "peripherals": [...]
-}
-```
-
-On peripherals you should choose `"clk_sel": 2` on connected devices.
+Peripherals typically should choose `"clk_sel": 2` for MMCX connection and `"clk_sel": 1` for external SMA connection.
+Refer to the [official docs](https://m-labs.hk/artiq/manual/core_drivers_reference.html) by searching for `clk_sel`.
+You may also need to add `"refclk": <number>` field to the target card.
 
 ## Setup external clocker
 
@@ -41,12 +32,12 @@ Here is example setup for SynthNV RF signal generator:
 1. Switch `CLK SEL` pin to `EXT`/`INT` according to customer needs
 2. Connect MMCx cables according to the customer needs and boards specifications (see image below for reference): 
    if the `INT` source is chosen, connect MMCx cable to `INT CLK`, otherwise connect external clocker to SMA `EXT CLK` 
-3. Connect the Clocker to the Kasli via 30-pin ports
+3. Connect the Clocker to the Kasli via 30-pin ports, or via external power supply
    ![](../img/clocker_ref.jpg)
 4. Connect the Clocker's SMA output to the Kasli's `CLK`/`CLK IN` SMA pin
-5. After assembling the crates and flashing the firmware, start Kasli and write config as follows:
+5. After assembling the crates and flashing the firmware, start Kasli and set config if needed:
    `artiq_coremgmt config write -s rtio_clock ext0_bypass`. Please refer to the [official manual](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
-   for the details and available options
+   for the details and available options. In most cases you may skip this step.
 6. Reboot either via `artiq_coremgmt reboot` or via power supply if the board's firmware doesn't have such command
 
 ## Testing

src/hw/mirny_almazny.md

@@ -9,10 +9,63 @@
 {
   "type": "mirny",
   "almazny": true, // for mirny with almazny only 
-  "ports": [<port num>]
+  "ports": [<port num>],
+  "clk_sel": 2, // optional
+  "refclk": 125e6 // optional
 }
 ```
 
+## Getting the firmware
+
+Here is [Mirny 0.3.1 firmware](../extra/mirny/mirny-0.3.1.zip). It contains a single ``.jed`` file that can be flashed following [flashing instructions](#flashing).
+
+### Building firmware (optional)
+
+However, if you need to make chances or build from source, follow these instructions.
+
+Once you get your hands on the firmware source code, you will need to work around few shortcomings of Nix, mainly not being able to run dynamically linked executables.
+
+You will need:
+- Xilinx ISE 14.7 installed on your system (this guide is assuming ``/opt/Xilinx`` path),
+- an environment with Migen.
+
+One way to do it is to create an FHS environment, like ARTIQ does for Vivado, within ARTIQ's ``flake.nix`` (to leverage Migen already being there), by adding these lines:
+
+```
+iseEnv = pkgs.buildFHSEnv {
+  name = "ise-env";
+  targetPkgs = vivadoDeps;
+};
+
+ise = pkgs.buildFHSEnv {
+  name = "ise";
+  targetPkgs = vivadoDeps;
+  profile = "set -e; source /opt/Xilinx/14.7/ISE_DS/settings64.sh";
+  runScript = "ise";
+};
+```
+
+Add them below ``vivadoEnv``. Then add ``iseEnv`` and ``ise`` to the dev shell's build inputs. Call ``nix develop`` on that.
+
+Then you can build Mirny:
+
+```shell
+nix develop
+ise-env
+cd ../mirny  # or wherever your source is at
+source /opt/Xilinx/14.7/ISE_DS/settings64.sh
+python mirny_impl.py
+```
+
+### Flashing
+
+For flashing, you will need Xilinx ISE 14.7 installed on your system (here assuming ``/opt/Xilinx`` path), and ``xc3sprog`` with the appropriate HS2 JTAG adapter.
+
+```shell
+nix-shell -p xc3sprog
+xc3sprog -c jtaghs2 -m /opt/Xilinx/14.7/ISE_DS/ISE/xbr/data -v build/mirny.jed
+```
+
 ## Testing
 
 ### Without Almazny
@@ -37,8 +90,8 @@ mirny0_ch3 info: {'f_outA': 1300000000.0, 'f_outB': 10400000000, 'output_divider
 After running `artiq_sinara_test`:
 
 1. Install gqrx `nix-shell -p gqrx`
-2. Connect bladeRF via USB cable only
-3. Run gqrx and choose `BladeRF #<number>...`
+2. Connect HackRF One via USB cable only
+3. Run gqrx and choose `HackRF HackRF One...`
 4. Default settings
 5. When gqrx loaded, start DSP processing with frequency at mirnyN_chM freq
 6. Connect the probe through attenuator to the Mirny's port
@@ -47,7 +100,7 @@ After running `artiq_sinara_test`:
 
 ![](../img/mirny_gqrx.png)
 
-### With Almazny
+### With Almazny (ARTIQ 7)
 
 At first, `artiq_sinara_test` will prompt you for testing Mirnies as the would be without Almazny.
 After that, it will prompt you with testing the Almazny:
@@ -95,4 +148,6 @@ You should also see differences in various modes, but that may require disabling
 
 ### Tips
 
-Mirnies often fail `ValueError: MUXOUT not high`, in that case restart the tests or reboot the board(s).
+~~Mirnies often fail `ValueError: MUXOUT not high`, in that case restart the tests or reboot the board(s).~~ - fixed in [9569cfb](https://github.com/m-labs/artiq/commit/9569cfb26329c0acdc1705d3256d2506b7bccce5)
+
+For Almazny v1.2+ support, CPLD firmware 0.3.1+ (with fixes) must be flashed onto Mirny.

src/hw/phaser.md

@@ -25,9 +25,9 @@ phaser0 10+0 10+1 10+2 10+3 10+4 MHz
 ### Upconverter
 
 1. Install gqrx `nix-shell -p gqrx`
-2. Connect bladeRF via USB cable only
-3. Run gqrx and choose `Nuand bladeRF SN <number>...`
-4. Input rate 20000000, other settings are default
+2. Connect HackRF One via USB cable only
+3. Run gqrx and choose `HackRF HackRF One...`
+4. Default settings
 5. Lower the gain in `Input options`
 6. When gqrx loaded, start DSP processing with frequency near 2.875 GHz +- DUC frequencies from `artiq_sinara_test`
    in `Receiver Options`
@@ -39,11 +39,7 @@ phaser0 10+0 10+1 10+2 10+3 10+4 MHz
 
 ### Baseband
 
-1. Install gqrx `nix-shell -p gqrx`
-2. Connect bladeRF via USB cable only
-3. Run gqrx and choose `Nuand bladeRF SN <number>...`
-4. Input rate 15000000, other settings are default
-5. When gqrx loaded, start DSP processing with frequency near 2.875 GHz (???)
-6. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
-7. You should see 5 tones on `artiq_sinara_test`'s frequencies (???):
-   ![phaser_baseband.png](../img/phaser_baseband.png)
+1. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
+2. Find FTT (Fourier Transform) function in the oscilloscope
+3. Start processing with frequency near DUC frequencies from `artiq_sinara_test`
+4. You should see 5 tones on `artiq_sinara_test`'s frequencies

src/hw/sampler.md

@@ -32,4 +32,5 @@ PASSED
 
 1. Apply 1.5V (connect the AA-battery) to the `samplerX`'s requested channel
 2. Press `Enter`, the `artiq_sinara_test` should output `PASSED`
-3. Repeat steps 1-2 for every available channel.
+3. Repeat steps 1-2 for every available channel.
+4. Disassemble AA-battery tool as it risks getting corrosion

src/hw/stabilizer.md

@@ -4,13 +4,83 @@
 * [QUARTIQ Manual](https://quartiq.de/stabilizer/)
 * [Firmware](https://github.com/quartiq/stabilizer)
 
+EEM is used for power only, and it can be alternatively powered by 12V barrel jack or PoE.
+
 ## JSON
 
-No JSON modifications required.
+Not present in the JSON.
+
+## Getting the firmware
+
+You can get the firmware from [Hydra](https://nixbld.m-labs.hk/jobset/mcu/mcu-contrib).
+
+* ``stabilizer-dual-iir`` supports Pounder v1.2 - probably you should flash this one,
+* ``stabilizer-dual-iir-pounder_v1_0`` supports Pounder 1.0 and 1.1 (legacy),
+* ``stabilizer-lockin`` is a different application which we do not usually flash.
+
+These all include changes to the mainline code to include Pounder telemetry.
+
+### Building (optional)
+
+Please keep in mind that the firmware from the official Quartiq repository does not include support for Pounder in MQTT, you may need to use a fork for that. But if the stabilizer is without a Pounder, it's also a valid option.
+
+There is no Nix Flake support to make things easier, so you need to set up rust and cargo manually. Start with cloning the stabilizer repository and opening a new shell with dfu-util (for flashing) and rustup (for building).
+
+```
+nix-shell -p dfu-util rustup
+```
+
+Set up the toolchain, this should be done only once:
+
+```
+rustup target add thumbv7em-none-eabihf
+cargo install cargo-binutils
+rustup component add llvm-tools-preview
+rustup update
+rustup default stable
+```
+
+Building:
+
+```
+cargo build --release
+cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
+```
+
+## Flashing
+
+Once you have the binary, you can now flash it.
+
+Without firmware on the device or with older firmware (without USB serial console), you need to use the jumper method:
+
+1. Have the Stabilizer disconnected from power.
+2. Use a jumper of some sort to short BOOT pins on the board.
+3. Turn on the power.
+4. You can remove the jumper after few seconds.
+
+With newer firmware with USB serial console:
+
+1. Connect the Stabilizer to power.
+2. Connect USB cable to the Stabilizer.
+3. Connect with a serial console emulator, usually at ``/dev/ttyACM0``.
+4. Input ``platform dfu`` in the console.
+
+And for both:
+
+5. The device is now in DFU mode.
+6. Flash the device with the following command:
+
+```
+dfu-util -a 0 -s 0x08000000:leave -R -D dual-iir.bin
+```
+
+7. Look for "File downloaded successfully".
+
+For normal usage, the stabilizer must be configured with USB console later (try ``help`` command first), to set its IP address and MQTT broker address. However, for general testing (like the one below), you don't need to configure it any further.
 
 ## Testing
 
-1. Ensure that the [firmware](https://github.com/quartiq/stabilizer) has been flashed onto the Stabilizer
+1. Ensure that the [firmware](#getting-the-firmware) has been flashed onto the Stabilizer
 2. Turn on the crate/Stabilizer via EEM cable or power supply
 3. Set up the signal generator for an amplitude of 1V, frequency of 10kHz, and a sine wave
 4. Use the splitter to connect the generator's output to ADC0 and to the oscilloscope (refer to the picture below)

src/hw/thermostat.md

@@ -23,6 +23,28 @@ dfu-util -a 0 -s 0x08000000:leave -D thermostat.bin
 Then check that fans are working properly.
 You may also check fan controls via `fan` commands (see the firmware documentation).
 
+## Test PID
+
+1. For Zotino: connect 10-pins IDC 2.54mm FC cable from internal Thermostat connector to the Zotino TEC
+2. General TEC: connect external connector to the TEC
+3. Connect Ethernet and PSU
+4. Run:
+   ```shell
+   git clone gitea@git.m-labs.hk:esavkin/thermostat.git
+   cd thermostat
+   git checkout zotino-tec
+   nix develop
+   python pytec/tec_qt.py
+   ```
+5. In `Output Config`, set limits: 
+   * `Max Cooling Current` - 400 mA
+   * `Max Heating Current` - 400 mA
+   * `Max Voltage Difference` - 1 V
+6. `PID Config` -> `PID Auto Tune` set desired target temperature, which should be slightly above your room temperature (+10C)
+7. Set `Thermistor Config` -> `B` and other values, according to the datasheet of the TEC module, for example for Zotino `B` is `3455 K`
+8. Run `PID Config` -> `PID Auto Tune` -> `Run` and check graphs that the measured temperature goes to the target temperature, 
+   and eventually stabilizes at +- 0.01 of the target
+
 ## Common problems
 
 ### Thermostat doesn't connect or doesn't enter DFU mode

src/hw/urukul.md

@@ -20,7 +20,8 @@
 
 ## Setup
 
-Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clocker source.
+Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clock source - either Clocker, 
+Kasli or external via SMA.
 
 ### Synchronization
 

src/hw/zotino_fastino.md

@@ -20,8 +20,7 @@
 }
 ```
 
-Fastino uses two physical EEM channels, but in the JSON file there should be only one channel specified, 
-and it should be the one connected to Fastino's EEM0.
+Fastino uses one physical EEM channel, despite having two EEM ports.
 
 ## Setup
 
@@ -57,18 +56,23 @@ Press ENTER when done.
 This may happen when power-cycle is too short. Power down the crate, wait at least 30 seconds, and power up again.
 [Issue](https://github.com/sinara-hw/Zotino/issues/37).
 
-### Zero voltage output on Fastino
+### Zero/meaningless voltage output on Fastino
 
-Some Fastino may not output any voltage during testing, usually that means it has no gateware.
+Some Fastino may not output any meaningful voltage during testing, usually that means it has no gateware flashed.
 
 Another common symptom of no gateware is that no LEDs are lit up. Whereas if the gateware has been flashed, the PG and FD LEDs will be lit green.
 
-You can flash the gateware with a standalone Kasli/Kasli-SoC:
+You can flash the gateware with a Kasli/Kasli-SoC, be it in the crate or standalone (no specific gateware needed for Kasli/SoC):
 
-1. Download the latest `fastino.bin` release from [quartiq/fastino](https://github.com/quartiq/fastino/releases)
-2. Run `git clone https://github.com/quartiq/kasli-i2c.git` and place `fastino.bin` in the kasli-i2c directory
-2. Connect the Fastino's EEM0 to any available Kasli/Kasli-SoC EEM port (**do not hot-plug**)
-3. Power on the standalone Kasli/Kasli-SoC
-4. Run `nix-shell -p python311Packages.pyftdi`
-5. Run `cd kasli-i2c; python flash_fastino.py 0 EEM<number> write fastino.bin` where `<number>` is the EEM port number on the Kasli/Kasli-SoC side
-6. If PG and FD LEDs are lit green, the Fastino is ready.
+1. Download the latest `fastino.bin` release from [quartiq/fastino](https://github.com/quartiq/fastino/releases).
+2. Run `git clone https://github.com/quartiq/kasli-i2c.git` and place `fastino.bin` in the kasli-i2c directory.
+3. Connect the Fastino's EEM0 to any available Kasli/Kasli-SoC EEM port ([**do not hot-plug**](../build_test_firmware.md#operating-hints-and-warnings)). 
+   You may skip this step if Fastino is connected within a crate.
+4. Power on the standalone Kasli/Kasli-SoC and connect it to the PC via data micro-USB.
+5. Run `nix-shell -p python311Packages.pyftdi`.
+6. Run `cd kasli-i2c; python flash_fastino.py 0 EEM<number> write fastino.bin` where `<number>` is the EEM port number on the Kasli/Kasli-SoC side.
+7. If PG and FD LEDs are lit green, the Fastino is ready.
+
+### Fastino output is 10V
+
+Fastinos by default after power up output 10V on all channels if not driven by the test otherwise. Make sure the EEM ports are specified correctly in the JSON and the EEM cable is connected to EEM0 on the Fastino.

src/sw_sup/artiq_start.md

@@ -0,0 +1,38 @@
+# Starting with ARTIQ
+
+This page describes how to start with ARTIQ system for novice users.
+
+## Connecting wires
+
+In most cases the system is shipped with power bricks (PSU), DC splitters and SFPs enough to power and control the whole system.
+Connect them in following order:
+1. Insert Ethernet SFP into the SFP0 of the master or standalone Kasli/Kasli-SoC (Carrier)
+2. Connect these SFPs to the router or PC via Ethernet cable (in some cases, optical cable)
+3. Insert optic/direct attach SFPs into the master and satellite Carriers, respective to the numeration, [more info in DRTIO page](drtio.md)
+4. Power on PSU or EEM power module, by inserting C14 cable, attach DC splitters if available
+5. Some cards may have "External power" setting (check the quotation), in this case, insert DC connector into the port
+6. Insert remaining cables into the Carriers (not applicable in case of EEM Power Module).
+
+## Set the network
+
+By default standalone/master Carriers arrive with 192.168.1.75/24 set as their static address. Carrier will try to acquire this address
+from your router, and in case of failure, they will be just unavailable from the network. Check the following articles for troubleshooting network issues:
+* [Networking](networking.md)
+* [Official docs](https://m-labs.hk/artiq/manual/installing.html#setting-up-the-core-device-ip-networking)
+
+## Run first experiment via artiq_run
+
+Before diving in to the repository experiments management and scheduling, it is essential to try run your first experiment
+via most basic way - `artiq_run`. For this you need to enter your ARTIQ environment (console) and run:
+```shell
+artiq_run --device-db path/to/device_db.py path/to/experiment.py
+```
+
+In case your directory contains relevant `device_db` file, you may omit the `--device-db path/to/device_db.py` part.
+To check this, you may run `ls .` and check if it is in the list.
+
+On pre-installed NUCs, the ARTIQ commands are available everywhere, and you just need to run them.
+If you have Nix package manager or NixOS, you will just need to enter the shell with `nix develop github:m-labs/artiq\?ref=release-7`.
+If you have installed ARTIQ with Conda, you will need to activate the environment with `conda activate <name of the environment with ARTIQ>`.
+
+You may check for experiments in the [official docs](https://m-labs.hk/artiq/manual/getting_started_core.html).

src/sw_sup/drtio.md

@@ -45,3 +45,9 @@ During the connection, the clock signal is being distributed, effectively making
 * Wrong setups - master to master, standalone to standalone. Messing up with SFP ports generally makes it unusable,
   but the connection should be established in most cases.
 * The fiber adapters are not symmetrical - if one end has 1270/1330 label, another one should be 1330/1270.
+
+
+### Master-satellite interrupted/unstable connection
+
+This often happens due to overheating issues. Check if the Kasli/SoC fans are working properly and
+try installing rack fans to increase the air flow.