Voltage Controlled Oscillator — Control Systems/Waveform Functions
Control_Systems/Waveform_Functions/Voltage_Controlled_Oscillator · 1 input / 1 output port(s) at insert · exports to Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text
Description#
The block's own DESCRIPTION_HTML, rendered verbatim — the same text the config dialog's info panel and the library navigator show. Fix a wrong sentence in the block's .cpp (R-D9), never here.
Voltage Controlled Oscillator
Control Systems / Waveform Functions
An oscillator whose instantaneous frequency follows its input:
f(t) = Fc + Δf·x(t), and y = cos(φ) with φ[k] = φ[k−1] + 2πFcTs + 2πΔf·Ts·x[k]
So a control of x = 0 oscillates at the carrier Fc,
x = +1 at Fc+Δf and x = −1 at
Fc−Δf. The phase is a running sum of the control
– a rectangular integral, the same one MATLAB's vco takes
– so what the block tracks is the input's history, not just its
present value.
Ports
- x – the control signal, scalar. Nominally in [−1, +1], which is the range that maps onto Fc ± Δf; a value outside it is not refused and simply carries the frequency further (see Notes).
- y – the oscillation, scalar, amplitude 1.
Parameters
- Carrier Frequency (Hz) – Fc, the frequency at a control of zero. Any real value; a negative one simply runs the phase backwards.
- Frequency Deviation (Hz) – Δf, how far a control
of ±1 moves the frequency. Setting it EQUAL to the carrier reproduces
MATLAB's
vco(x, Fc, Fs), whose default deviation is the carrier itself – so x = −1 stands still and x = +1 runs at twice the carrier. - Initial Phase (rad) – added to the accumulated phase before the cosine is taken, so it shifts the waveform without disturbing the frequency. It is not accumulated.
- Output Function – cos (MATLAB's, and the default) or sin, which is the same wave a quarter cycle later.
- Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text.
Both frequencies are structural: they are folded into two phase increments using the block's own period and inlined at export time rather than exposed as tunable parameters – the period is part of the constant, so a core exported at one rate does not carry the frequency to another. Re-export after changing either.
The three HDL targets are simulation-only, and only because of
the trigonometric call: the phase accumulation and the wrap stay in the Q16.16
datapath, and just the closing cosine converts at the port boundary and
evaluates in real. The synthesizable form of this block is a phase
accumulator driving a lookup table, which is a different block.
Simulink bridge
No equivalent (Support::None). vco is a
Signal Processing Toolbox function, and that toolbox ships no Simulink
library at all. The nearest block in the installed toolboxes is DSP System
Toolbox's NCO, which is a different block: it is told a phase
increment and a quantized lookup table, not a carrier and a deviation in hertz,
and its whole point is the table this block does not have. Mapping onto it would
misreport what crossed, so the bridge reports this block instead and it carries
no parity testbench. Code export verification still covers it across all
ten languages.
Notes
- Stateful, and discrete by nature
(
setDiscreteOnlyBlock(true)): the phase advances once per sample. - The first sample already carries its own control value. MATLAB's
cumsumincludes it while the carrier term is still zero, so y[0] = cos(2πΔf·Ts·x[0] + initial phase). The block reproduces that rather than starting one carrier step ahead. - A control outside [−1, +1] is not refused, where MATLAB's function rejects one. It can only make that check because it holds the whole signal at once; a streaming block sees one sample and would have to refuse late or not at all. The frequency simply carries on beyond Fc ± Δf, and a frequency past half the sampling rate aliases, as any sampled oscillation does.
- Scalar only: one control, one phase. Wire one block per channel.
- The phase is wrapped into 0, 2π) every sample. It changes no value, and it is what keeps the accumulator inside the fixed-point range the HDL cores carry.
- No state space. The block is not linear in its input – the input moves a frequency, and the output is a cosine of an integral – so it carries none and model reduction correctly declines to merge it.
Code facts#
| Fact | Value |
|---|---|
| registered type | Control_Systems/Waveform_Functions/Voltage_Controlled_Oscillator |
| family | Control_Systems/Waveform_Functions |
| solver environment class | ICoreBlock_0_Control_Systems_1_Waveform_Functions_2_Voltage_Controlled_Oscillator |
| source | [src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Waveform_Functions/Voltage_Controlled_Oscillator/ICoreBlock_0_Control_Systems_1_Waveform_Functions_2_Voltage_Controlled_Oscillator.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Control_Systems/Waveform_Functions/Voltage_Controlled_Oscillator/ICoreBlock_0_Control_Systems_1_Waveform_Functions_2_Voltage_Controlled_Oscillator.h |
| default size on canvas | 124 × 76 px |
| ports at insert | 1 in, 1 out |
| code generators implemented | Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text |
Ports#
| # | Direction | Signal type | Description label |
|---|---|---|---|
| 1 | in | ICoreDouble | x |
| 2 | out | ICoreDouble | y |
Ports the constructor creates. A block whose port list changes with its configuration adds or removes ports at load time; the count above is the one a freshly inserted block has.
Configuration variables#
| Config variable | Default | Simulink parameter |
|---|---|---|
Carrier Frequency (Hz) | 1 | — |
Frequency Deviation (Hz) | 1 | — |
Initial Phase (rad) | 0 | — |
Output Function | cos%~%sin~~cos | — |
Every block also carries Sampling Time (s) from ICoreBlockSolverEnvironment: zero or less inherits the solver's rate, a positive value runs the block at that period.
Simulink bridge#
| support | Support::None |
| Simulink path | — |
| port-count rule | PortsParam::None |
SampleTime parameter | yes |
Caveat (shown to the user): no Simulink equivalent: vco() is a Signal Processing Toolbox FUNCTION and that toolbox ships no Simulink library at all. The nearest installed block, DSP System Toolbox's NCO, is a different block -- it takes a phase increment and a quantized lookup table rather than a carrier and a deviation in hertz -- so mapping onto it would misreport what crossed. Reported rather than dropped, and it carries no parity testbench
Catalog contract: src/ICoreBlocks/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h
Description vs code#
The lists agree. check_block_descriptions.py finds no disagreement between the description's Ports, Parameters, Code export and Simulink bridge lists and the code's.
The verdict above is
tools/docs/check_block_descriptions.py(P7.1), which compares LISTS. It cannot read a sentence: "stateless" on a block with a state, an initial-value semantic the recursion does not implement, a "not synthesizable" caveat the HDL banner contradicts. That is the agent audit (P7.3) on BLOCK_DESCRIPTION_AUDIT.md, and this tool's green is not a substitute for one.
File banner (developer view)#
The top comment of the block's .cpp — the maths, the realization and the export strategy, addressed to whoever changes it. It must not contradict the description above (P7.5).
Voltage Controlled Oscillator -- instantaneous frequency f = Fc + Df*x, one phase register THE RECURSION IS READ OUT OF THE FUNCTION. MATLAB's vco() hands its work to modulate(..., 'fm'), whose one line is y = cos(2*pi*Fc*t + kf*cumsum(x)) with kf = 2*pi*Df/Fs and t = k/Fs from k = 0. Two consequences, both reproduced here exactly: cumsum INCLUDES the current sample, so y[0] already carries kf*x[0] while the carrier term is still zero; and the integral is a plain running sum, not a trapezoid.
So the state holds the phase WITHOUT this sample's contribution, the output is taken from state + kf*x, and the carrier step is added afterwards. Getting that order backwards costs exactly one carrier step on every sample -- a lag no test of a CONSTANT input can see, which is why the rig drives it with a signal that moves.
⚠ THE PHASE IS WRAPPED into [0, 2*pi) every sample. Mathematically that changes nothing. It is what keeps the accumulator inside the Q16.16 range the three HDL targets carry, and what stops a long run spending its resolution on a growing number.
⚠ THE THREE HDL TARGETS ARE SIMULATION-ONLY, and only because of the cosine: the phase arithmetic and the wrap stay in the fixed-point datapath, and just the final trigonometric call converts at the port boundary and evaluates in
real. A synthesizable version of this block is a lookup table, which is a different block (Simulink calls it an NCO).
Sample results#
The same rig also ran:
| Stimulus | What it is | Output range |
|---|---|---|
impulse | Impulse: one sample of 1 at k = 5, 0 elsewhere (Repeating Sequence Stair) | -1 … 1 |
ramp | Ramp: slope 1 from t = 0 | -1 … 1 |
sine | Sine Wave: amplitude 1, 2 rad/s, no phase, no bias | -1 … 1 |
table | Repeating Sequence Stair: [-2 -1 -0.5 0 0.5 1 2 3], one entry per sample | -1 … 1 |
Plotted: step — Step: 0 -> 1 at t = 1 s
Category dynamic · sample time 0.1 · 60 steps · commit a7ce80a788b799b1061c3aed0328d10563706ca6 · produced by docsSample --out <folder> --blocks Uniform_Encode Uniform_Decode Voltage_Controlled_Oscillator --steps 60 · data docs/generated/samples/Control_Systems__Waveform_Functions__Voltage_Controlled_Oscillator.json · the SVG is generated from those numbers by tools/docs/plot_svg.py, so it is a run and not a drawing (R-D10).