Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The driver contract

The traits that a driver implements, in crates/oscyl-driver/src/contract.rs. Each method links to its documentation in the API reference. ADR 0002 records why the contract is made this way.

A driver is a crate under crates/drivers/ that exposes one pub static DRIVER. Its folder and its driver id (Info::id) are <vendor>-<model>, and its package is oscyl-<vendor>-<model>, for example oscyl-korg-minilogue-xd. A crate that a family of synths shares is oscyl-<family>, as oscyl-logue. The tutorial’s oscyl-tutorial-synth is the one exception. Of the 53 methods of Driver, 18 are required, and the other 35 have defaults. The apps use it only as &dyn Driver. A required method has no default. An optional method has a default that suits a driver which does not use it.

Driver

One synth model: everything that the apps know about it.

Identity

MethodRequiredWhat it gives
infoYesThe driver’s id, the maker and the model.
recognizeYesWhether an answer to the MIDI device inquiry comes from this synth.
port_hintYesSubstrings of the names of the MIDI ports that the synth shows.
firmwareNoThe firmware version that an identity reply names. Default: none.
setup_hintNoWhat to check on the synth when it does not answer the inquiry. Default: empty.
tierNoThe driver’s support tier. Default: 3.
voicesNoThe polyphony of the models that it covers. Default: unknown.

What the synth has

MethodRequiredWhat it gives
capabilitiesYesThe banks and their slots, which banks are writable, the edit buffer, live changes and unit slots.

The program

MethodRequiredWhat it gives
fieldsYesThe parameters: name, group and range.
init_programYesA new, valid program.
check_programYesRefuses bytes that are not a whole program.
getYesA field’s raw value.
setYesSets one field, and no other.
nameYesThe program’s name.
set_nameYesSets the name.
name_rulesYesThe longest name and the characters that a name can hold.

Files

MethodRequiredWhat it gives
file_formatsYesThe synth’s own file formats. Can be empty.
importYesReads a file of one of those formats.
exportYesWrites a file. Importing it gives back the same library.

The editor

MethodRequiredWhat it gives
curationYesThe editor’s pages and sections. A simple driver can return curation_by_group(self.fields()).
controlNoThe control for a field: a dial, a switch, named choices or named bands. Default: a switch for a two-value field, else a dial.
short_labelNoA short label inside a titled section. Default: the field’s name.
label_inNoThe label when a field’s job depends on another field. Default: the short label.
emphasizedNoWhether a field is a main control, which apps draw larger. Default: no.
format_valueNoA field’s value as text, in the context of the program. Default: format_raw of the value.
format_rawNoA raw value as text, with no program. Default: the number, or Off and On for a two-value field.
page_summaryNoOne line on a page’s state. Default: empty.
page_summary_inNoThe page summary, short or translated, for an app. Default: page_summary.
graphsNoPictures of a page. Default: none.
handlesNoDraggable points on a page’s first graph. Default: none.
dragNoThe field values for a handle at a point. Default: none.
relevantNoWhether a field does anything with the other settings. Default: yes.
helpNoWhat a field does. Default: empty.
categoryNoWhat kind of sound a program is. Default: unknown.
categoriesNoEvery category, for filters. Default: none.
list_facetNoA choice field that program lists can filter by. Default: none.

Generate

MethodRequiredWhat it gives
charactersNoThe kinds of sound that Generate makes. Default: none, so the driver does not generate.
macro_infoNoThe titles and help of the four dials. Default: Bright, Movement, Grit and Ambience.
mutabilityNoWhat generation may do to a field. Default: keep it.
generateNoA new program from a recipe.
varyNoA variation of a program.
breedNoA child of two programs.
morphNoA step between two programs. Default: morph_fields.
generated_nameNoA name for a generated program. Default: the character’s title and a number.
needsNoThe user unit slots that a program relies on. Default: none.
unit_paramNoWhich user unit parameter a field is. Default: none.

Live and the panel

MethodRequiredWhat it gives
live_messagesNoThe MIDI messages that set one field on the sounding voices. Default: none, so apps send the whole program.
program_slotNoThe slot that the synth’s panel picked, from Bank Select and Program Change. Default: unknown.
panel_listenerNoA decoder for the Control Changes that the panel sends. Default: none.

Sessions and demo

MethodRequiredWhat it gives
sessionYesA new session for one synth.
simulatorYesA new simulated synth.
demo_libraryNoA library to explore without a synth. Default: one generated program for each character.
demo_simulatorNoThe simulated synth of demo mode. Default: simulator.

DriverSession

The synth’s protocol for one connected synth, sans IO: it never touches a port or a clock. Oscyl gives it the bytes and the time. Most sessions keep an Engine, the request engine, which keeps one request in flight. Every method is required.

MethodWhat it does
submitPlans an operation. A bad slot, a write to a factory slot or a bad program fails here, and nothing is sent.
is_idleTrue when nothing is queued or in flight.
poll_transmitThe next bytes to send, if the session sends now.
next_deadlineWhen a request in flight times out.
handle_timeoutTime passed: a request whose reply did not come fails.
handle_inputBytes from the synth, in fragments of any size.
poll_eventThe next result, in order.

An operation is a SessionOp: ReadCurrent, ReadPrograms, WritePrograms or Audition. Its results are SessionEvents: Current, Program, Progress, then Done or Failed.

Simulator

The synth itself, in code, sans IO. The conformance suite and demo mode talk to it. Every method is required.

MethodWhat it does
handleOne message in, the synth’s replies out.
idle_tickOne pass of the firmware’s main loop, with no MIDI traffic.
programThe program in a slot.
edit_bufferThe edit buffer’s program.
is_settledNo save is pending and no reply state is corrupt.
faultsThe faults seen on the hardware that inject can switch on. It must include lose_reply.
injectSwitches a fault on.

PanelListener

An optional decoder of the Control Changes that a synth’s panel sends, from Driver::panel_listener. Its one method, control, gives the field and the value that a Control Change sets, once the value is complete.

What the conformance suite checks

oscyl_conformance::run(&DRIVER) runs these checks in order, against the driver’s simulator. A failure panics with <driver id>: <check>: <what>.

CheckWhat it proves
init_programThe init program is valid, and its name is not empty and uses allowed characters.
fieldsEvery field takes its minimum and its maximum, reads them back, and changes no other field. One step outside the range is refused.
namesA name of the longest length reads back. One character more is refused.
wrong_length_programsA program one byte short or one byte long is refused by every method that takes a program.
rejects_bad_targetsA write to a factory slot or past the last slot, and a read past the last slot, fail at submit and send nothing.
file_formats_round_tripEvery file format gives back the programs, and the author and comment when it keeps them. A second round trip changes nothing. An unknown format is refused.
write_then_read_backA write to the first, second and last slot of each writable bank ends Done. The simulator then holds the programs and is settled, and a read gives them back.
auditionWith an edit buffer: an audition ends Done, the edit buffer holds the program, and ReadCurrent gives it back.
progressReads and writes report progress that rises to the total, and Done comes last.
faults_never_report_false_successWith each fault: a write that ends Done stored every program, and a read returns only what the synth holds.
lost_replies_failThe simulator has lose_reply. With it, every operation ends Failed.
curation_covers_every_fieldEvery field is in exactly one section or excluded, and at least one is shown. Every shown field has a label and a control that fits it.
formats_every_valueEvery field’s minimum and maximum format as text that is not empty.
generation_is_deterministic_and_validFor each character, the same recipe gives the same bytes, and every value is in range. Kept fields and pages stay, and vary, breed and morph behave.
live_messages_are_well_formedLive messages exist only with live_changes, and each one is one complete channel message on the channel asked for.
presentation_is_consistentEmphasized fields are shown, labels exist, categories are listed, and graphs, handles and drags stay within the pages and fields.
recognizes_its_simulatorPort hints exist. The driver recognises its simulator’s identity reply from any channel, but not the inquiry itself and not another maker’s reply.
app_hooksThe demo library is valid and fits the writable slots, the demo simulator is recognised, and the list facet is an in-range choice field.