Update hardware instructions to better match real testing processes

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

flake.lock

@@ -2,16 +2,16 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1697851979,
+        "lastModified": 1710695816,
-        "narHash": "sha256-lJ8k4qkkwdvi+t/Xc6Fn74kUuobpu9ynPGxNZR6OwoA=",
+        "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/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_low": "input", // or "output"
-  "bank_direction_high": "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
+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`.
-  "hw_rev": "<hw rev>",
+You may also need to add `"refclk": <number>` field to the target card.
-  "base": "<base>",
-  ...
-  "ext_ref_frequency": <freq in Hz>,
-  ...
-  "peripherals": [...]
-}
-```
-
-On peripherals you should choose `"clk_sel": 2` on connected devices.
 
 ## 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,7 +9,9 @@
 {
   "type": "mirny",
   "almazny": true, // for mirny with almazny only 
-  "ports": [<port num>]
+  "ports": [<port num>],
+  "clk_sel": 2, // optional
+  "refclk": 125e6 // optional
 }
 ```
 
@@ -37,8 +39,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
+2. Connect HackRF One via USB cable only
-3. Run gqrx and choose `BladeRF #<number>...`
+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

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
+2. Connect HackRF One via USB cable only
-3. Run gqrx and choose `Nuand bladeRF SN <number>...`
+3. Run gqrx and choose `HackRF HackRF One...`
-4. Input rate 20000000, other settings are default
+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`
+1. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
-2. Connect bladeRF via USB cable only
+2. Find FTT (Fourier Transform) function in the oscilloscope
-3. Run gqrx and choose `Nuand bladeRF SN <number>...`
+3. Start processing with frequency near DUC frequencies from `artiq_sinara_test`
-4. Input rate 15000000, other settings are default
+4. You should see 5 tones on `artiq_sinara_test`'s frequencies
-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)

src/hw/sampler.md

@@ -33,3 +33,4 @@ 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.
+4. Disassemble AA-battery tool as it risks getting corrosion

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, 
+Fastino uses one physical EEM channel, despite having two EEM ports.
-and it should be the one connected to Fastino's EEM0.
 
 ## Setup