applet.control.si5351a_ng: Advanced clockgen control applet including FPGA-timed sequencing and sweeps.

[i-infra]

The existing control-si535x applet was missing quite a few features that I needed, so I built this applet referencing pavelmc's Si5351mcu to support setting frequency directly, and more importantly, support hardware-timed frequency transitions (for smooth sweeps, etc), and -

This also supports a 'sequence' mode, which accepts (via stdin) a list of CSV frequency,duration pairs, for use with my digimoder.py, turning glasgow + si5351a (+ recommended GPS receiver w PPS output or frequency reference) into a sort of software-defined radio transmitter for digital signaling modes on bands up to the 2m band.

It's a relatively expansive applet, but I have been making considerable use out of it recently, and made successful contacts on a variety of bands.

usage: glasgow run control-si5351a-ng [-h] [-V SPEC] [--scl PIN] [--sda PIN] [--i2c-address ADDR] [--xtal-freq HZ] [--ppb PPB] [--vco-max HZ] [--clock-ppm PPM] OPERATION ...

Control a Si5351A programmable clock generator with direct frequency setting, drive strength control, and click-noise-free operation.

This applet computes PLL and multisynth divider parameters on the host and writes them to the device over I²C. It uses integer-only output dividers and maximizes VCO frequency for best phase noise.

Frequency range: ~8 kHz to 225 MHz (output dependent).

For raw register access or ClockBuilder Pro CSV loading, use the ``control-si535x`` applet instead.

positional arguments:
  OPERATION
    set-freq          set output frequency
    enable            enable clock output(s)
    disable           disable clock output(s)
    status            read device status
    sweep             sweep frequency range
    sweep-hw          hardware-timed frequency sweep (FPGA-precision timing)
    sequence          hardware-timed symbol sequence from CSV (freq_hz,duration_ms)
    plan              show frequency plan without writing to hardware
    sweep-plan        show sweep plan with click boundaries

options:
  -h, --help          show this help message and exit

configuration:
  -V, --voltage SPEC  configure I/O port voltage to SPEC (e.g.: '3.3', 'A=5.0,B=3.3', 'A=SA')
  --scl PIN           bind the applet I/O line 'scl' to PIN (default: 'A0', required)
  --sda PIN           bind the applet I/O line 'sda' to PIN (default: 'A1', required)
  --i2c-address ADDR  I2C address of the Si5351A (default: 0x60)
  --xtal-freq HZ      crystal/TCXO reference frequency in Hz (default: 25000000)
  --ppb PPB           TCXO frequency correction in parts-per-billion; positive = TCXO runs fast (output will be too high), negative = runs slow (default: 0)
  --vco-max HZ        maximum VCO frequency in Hz; values above 900 MHz overclock the Si5351 allowing out_div=6 at >150 MHz but with degraded phase noise (default: 900000000, safe overclock limit:
                      ~1_000_000_000)
  --clock-ppm PPM     FPGA oscillator error in parts-per-million; positive = FPGA clock runs fast (ticks are shorter than nominal, symbols finish early), negative = runs slow; corrects hardware-timed symbol
                      durations for sweep-hw and sequence (default: 0)

[whitequark]

That is a lot of code! I gave it a very cursory glance and I don't see any glaring issues, so in principle I would be for having this. As I mentioned earlier my code review time is a bit limited right now, but should be better in a week.

We do need to discuss a few things though:

• Is the I2C sequencer something we should make more generic and put into its own applet, or the I2C controller applet? I'm uncomfortable with pulling in implementation details; it may be necessary to make said implementation details public if the sequencer stays on its own. (Also, specifically the I2C initiator needs a refactor that have been bumped down the road by being currently mired in the UK settlement process and a few other things, so this concern is at the top of my mind.)
• This applet adds a very large amount of code and functionality. This isn't inherently a problem, but for all new applets (and a lot of new applets I've been porting to the new API in the background, cf. Migrate all applets to V2 API #826) I've been adding tests and documentation.
  • Documentation is an absolute prerequisite, but it should not be much more difficult than adding the usual argparse boilerplate. (You can copy the si535x.rst and modify accordingly.)
  • Ideally, there would be tests that achieve near-100% code coderage. The ideal is usually difficult or impossible to achieve (for example we do not have a CLI testing harness) and I consider anything that broadly exercises applet functionality to be acceptable for merging. At a minimum there needs to be an assertBuilds, but I would strongly prefer it that there be code utilizing the record-replay test harness that exercises the basic functions implemented in the CLI. Let me know if you need additional guidance here.

By the way, are Glasgow applets something you expect to be writing more of? While I haven't been able to spend a lot of time looking at the code (yet), my initial impression is very positive, and I find the ability to work with an unfamiliar codebase on this level pretty remarkable.

[i-infra]

I'll follow up with a full reply, tests, and docs soon! Mostly just wanted to get this code off my laptop 😅

By the way, are Glasgow applets something you expect to be writing more of?

Absolutely! Been following the project for quite some time, ordered 2x in 2020, and been using almost daily in recent weeks and months. It's a super useful tool and I have thoroughly enjoyed pushing the limits of the platform & using it for weird things (like prototyping radio transmitters :))

Cheers!

[whitequark]

It's a super useful tool and I have thoroughly enjoyed pushing the limits of the platform & using it for weird things (like prototyping radio transmitters :))

I've done this too! My roommate once said something about 125 MHz and I was like "I bet I can play Diggy Diggy Hole on his radio by modulating a carrier using the existing audio-dac applet and an FPGA PLL". Worked great!

Absolutely! Been following the project for quite some time, ordered 2x in 2020, and been using almost daily in recent weeks and months.

Excellent! In that case I would like to invite you to be a part of the maintenance team once your orientation is complete and you have a good understanding of what makes an applet well-maintainable. I think you're already pretty close and we desperately need more people here.

[whitequark]

I've sent you an invitation to the org. (Having write access to the repo is also necessary for CODEOWNERS to be able to ping you, but my offer covers more than that formality.)

[i-infra]

Is the I2C sequencer something we should make more generic and put into its own applet, or the I2C controller applet? I'm uncomfortable with pulling in implementation details; it may be necessary to make said implementation details public if the sequencer stays on its own. (Also, specifically the I2C initiator needs a refactor that have been bumped down the road by being currently mired in the UK settlement process and a few other things, so this concern is at the top of my mind.)

Trying to think of other i2c output-only devices where having precisely sequenced writes could be of use. Off the top of my head:

• DACs, like the MCP4725, for arbitrary waveform generation up to audio frequencies and/or VCO control?
• Haptics drivers, like the DA7280?
• Animations on the AiP33629 16x9 i2c LED driver used in disposable vapes

These three output-only devices might be enough to justify factoring it out into its own applet, or merging upstream into the i2c controller applet. Expanding the applet to support bi-directional R/W sequences via an on-FPGA state machine / DSL to support higher-chronological-precision sensor reads feels like an intimidating prospect, and not necessarily much bang for buck (right now).

Will try and get tests.py and at the very least the .rst boilerplate landed soon, understanding that your bandwidth is limited for the immediate future with UK settlement implementation details.

BTW very happy to hear you've landed somewhere relatively safe & comfortable! I read your increase in commit velocity on this project as a good sign of your general health and well-being.

And flattered by your offer of more uncompensated volunteer work maintainership - definitely think this project is worth continuing to support, and while functionally broke, I do have some time and bandwidth and would be happy to carry some weight. Looking forward to talking more / synchronously in the future.

[whitequark]

These three output-only devices might be enough to justify factoring it out into its own applet, or merging upstream into the i2c controller applet.

Let's not do it at the time being then; the effort (and ongoing overhead) doesn't seem worth the cause.

I read your increase in commit velocity on this project as a good sign of your general health and well-being.

No, my life is still a nightmare. This project is a nice escape, sometimes. (And having stable housing means I am physically capable of maintaining electronics.)

And flattered by your offer of more uncompensated volunteer work

It could be compensated, we just need to work out the details. It would have to come out of my own pocket (I receive nothing from sales of revC devices, and revD campaign hasn't started yet), and some people find that getting a low (compared to e.g. commercial work in Silicon Valley) rate devalues their work compared to getting nothing material, but it's something that can be arranged. I do know that this project will require dedicated full-time maintainers at some not-too-distant point if it is to continue at the trajectory that I have planned for it.

Looking forward to talking more / synchronously in the future.

IRC is preferred, Matrix is acceptable, Discord as a last resort. If you have it working, please go ahead and DM me on IRC whenever.