# AOUT

## Data Structures
struct | aout_channel_t
## Functions
s32 | AOUT_Init (u32 mode)
s32 | AOUT_IF_Init (u32 mode)
const char * | AOUT_IfNameGet (aout_if_t if_type)
s32 | AOUT_ConfigSet (aout_config_t config)
aout_config_t | AOUT_ConfigGet (void)
s32 | AOUT_ConfigChannelInvertedSet (u8 cv, u8 inverted)
s32 | AOUT_ConfigChannelHzVSet (u8 cv, u8 hz_v)
s32 | AOUT_CaliModeSet (u8 pin, aout_cali_mode_t mode)
aout_cali_mode_t | AOUT_CaliModeGet (void)
u8 | AOUT_CaliPinGet (void)
const char * | AOUT_CaliNameGet (aout_cali_mode_t mode)
s32 | AOUT_PinSet (u8 pin, u16 value)
s32 | AOUT_PinGet (u8 pin)
s32 | AOUT_PinSlewRateSet (u8 pin, u8 value)
s32 | AOUT_PinSlewRateGet (u8 pin)
s32 | AOUT_PinPitchRangeSet (u8 pin, u8 value)
s32 | AOUT_PinPitchRangeGet (u8 pin)
s32 | AOUT_PinPitchSet (u8 pin, s16 value)
s32 | AOUT_PinPitchGet (u8 pin)
s32 | AOUT_DigitalPinSet (u8 pin, u8 value)
s32 | AOUT_DigitalPinGet (u8 pin)
s32 | AOUT_DigitalPinsSet (u32 value)
u32 | AOUT_DigitalPinsGet (void)
s32 | AOUT_SuspendSet (u8 suspend)
s32 | AOUT_SuspendGet (void)
s32 | AOUT_Update (void)
s32 | AOUT_TerminalHelp (void *_output_function)
s32 | AOUT_TerminalParseLine (char *input, void *_output_function)
s32 | AOUT_TerminalPrintConfig (void *_output_function)

## Detailed Description

AOUT module driver

The application interface (API) has been tailored around AOUT modules, which are part of the MIDIbox Hardware Platform (MBHP), and MIOS based applications like MIDIbox CV (CV control via MIDI), MIDIbox SEQ (CV control from a sequencer) and MIDIbox SID/FM (CV control from a synthesizer)

The two "internal DAC" channels of the STM32F103RE are supported as well (AOUT_IF_INTDAC)

Up to 32 analog outputs are supported (*) An interface to control digital pins is available as well (**)

Output voltages are managed in 16bit resolution. Although none of the current modules support the full resolution, from programming and performance perspective it makes sense to organize CV values this way.

If 7bit values should be output, the caller has to left-align the value, e.g.

     AOUT_PinSet(0, value_7bit << 9); // left-align MSB to 16bit

Before voltage changes are transfered to the external hardware, the AOUT_PinSet function compares the new value with the current one. If equal, the register transfer will be omitted, otherwise it will be requested and performed once AOUT_Update() is called.

This method has two advantages:

- if AOUT_PinSet doesn't notice value changes, the appr. AOUT channels won't be updated to save CPU performance
- all CV pins will be updated at the same moment

(*) currently only limited by the aout_update_req variable. This could be enhanced in future if really required, but this would cost performance!

(**) currently only supported for MBHP_AOUT, since MAX525 provides such a digital output pin

Supported interface types:

- 0 (AOUT_IF_NONE): interface disabled, but SPI port will be initialized
- 1 (AOUT_IF_MAX525):
  CV: up to 8 cascaded MAX525 (MBHP_AOUT module), each MAX525 provides 4 channels with 12bit resolution
  Digital: 1 pin per IC
- 2 (AOUT_IF_74HC595):
  CV: up to 32 cascaded 74HC595 (each MBHP_AOUT_LC module provides 2 74HC595)
  Resolution is selectable with interface_option, each 74HC595 has an own bit which define:
  - 0: 12/4 bit configuration
  - 1: 8/8 bit configuration
  Examples:
  - 0x00000000: all AOUT_LC modules used for 12/4 bit configuration
  - 0xffffffff: all AOUT_LC modules used for 8/8 bit configuration
  - 0x00000003: first AOUT_LC used for 8/8 bit configuration, all others for 12/4
  - 0x0000000c: second AOUT_LC used for 8/8 bit configuration, all others for 12/4
  Digital: none
- 3 (AOUT_IF_TLV5630):
  CV: one TLV5630 (MBHP_AOUT_NG module) with 8 channels at 12bit resolution
  Digital: none
- 4 (AOUT_IF_MCP4922_1):
  CV: one MCP4922 with gain set to 1 with 2 channels at 12bit resolution
  Digital: none
- 4 (AOUT_IF_MCP4922_2):
  CV: one MCP4922 with gain set to 2 with 2 channels at 12bit resolution
  Digital: none
- 4 (AOUT_IF_INTDAC):
  CV: two channels available at pin RA4 (J16:RC1) and RA5 (J16:SC) at 12bit resolution
  Digital: none

Example for a complete module configuration:

       // initialize AOUT module
      AOUT_Init(0);

      // configure interface
      // see AOUT module documentation for available interfaces and options
      aout_config_t config;
      config = AOUT_ConfigGet();
      config.if_type = AOUT_IF_MAX525;
      config.if_option = 0;
      config.num_channels = 8;
      config.chn_inverted = 0;
      AOUT_ConfigSet(config);
      AOUT_IF_Init(0);

Hardware configuration (settings are located in aout.h, and can be overloaded in mios32_config.h if required):

- AOUT_NUM_CHANNELS (default: 8)
  Maximum number of AOUT channels (1..32)
  Number of channels within this range can be changed via soft-configuration during runtime.
- AOUT_SPI (default: 2)
  allowed values: 0 (J16), 1 (J8/9) and 2 (J19)
- AOUT_SPI_RC_PIN (default: 0)
  Only relevant for AOUT modules, not for AOUT_IF_INTDAC:
  Specifies the RC pin of the SPI port which should be used.
  Allowed values: 0 or 1 for SPI0 (J16:RC1, J16:RC2), 0 for SPI1 (J8/9:RC), 0 or 1 for SPI2 (J19:RC1, J19:RC2)
- AOUT_SPI_OUTPUTS_OD (default: 1 on STM32, 0 on LPC17 module)
  Only relevant for AOUT modules connected to MBHP_CORE_STM32 module, not for AOUT_IF_INTDAC:
  Specifies if output pins be used in Open Drain mode? (perfect for 3.3V->5V levelshifting)

For the default setup, the Module is connected to J19 of the MBHP_CORE_STM32 module:

- J19:Vs to AOUT Vs
- J19:Vd to AOUT Vd
- J19:SO to AOUT SI
- J19:SC to AOUT SC
- J19:RC1 to AOUT CS

Note that this is *not* an 1:1 pin assignment (an adapter has to be used)!

The voltage configuration jumper of J19 has to be set to 5V, and a 4x1k Pull-Up resistor array should be installed, since the IO pins are configured in open-drain mode for 3.3V->5V level shifting.

An usage example can be found under $MIOS32_PATH/apps/examples/aout

## Function Documentation

aout_cali_mode_t AOUT_CaliModeGet | ( | void |  | ) |

This function returns the current calibration mode

Returns:
  the calibration mode

s32 AOUT_CaliModeSet | ( | u8 | pin,
|  | aout_cali_mode_t | mode |
| ) |  |  |

This function enables calibration mode for a given pin

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)
  `[in]` | mode | the calibration mode

Returns:
  -1 if pin not available
  0 on success

Here is the call graph for this function:

const char* AOUT_CaliNameGet | ( | aout_cali_mode_t | mode | ) |

u8 AOUT_CaliPinGet | ( | void |  | ) |

This function returns the pin which is selected for calibration mode

Returns:
  the selected pin

s32 AOUT_ConfigChannelHzVSet | ( | u8 | cv,
|  | u8 | hz_v |
| ) |  |  |

gives direct access to the chn_hz_v field of the AOUT configuration

s32 AOUT_ConfigChannelInvertedSet | ( | u8 | cv,
|  | u8 | inverted |
| ) |  |  |

gives direct access to the chn_inverted field of the AOUT configuration

aout_config_t AOUT_ConfigGet | ( | void |  | ) |

Returns current AOUT configuration

Returns:
  config.if_type: the interface
  config.if_option: interface options
  config.num_channels: number of channels
  config.chn_inverted: pin inversion flags

s32 AOUT_ConfigSet | ( | aout_config_t | config | ) |

Configures the AOUT driver.

It is recommented to call AOUT_IF_Init() if a different AOUT interface type has been selected (e.g. switch from MBHP_AOUT to MBHP_AOUT_NG)

Parameters:

  `[in]` | config | a structure with following members: config.if_type: selects the interface config.if_option: allows to pass additional options to the IF driver config.num_channels: number of channels (1..AOUT_NUM_CHANNELS) config.chn_inverted: allows to invert the output of AOUT pins (each pin has a dedicated bit)

Returns:
  < 0 if initialisation failed

Here is the call graph for this function:

s32 AOUT_DigitalPinGet | ( | u8 | pin | ) |

This function returns the state of a digital pin.

Currently only the MAX5225 based MBHP_AOUT module supports two digital pins

Parameters:

  `[in]` | pin | the pin number (0..31)

Returns:
  -1 if pin number too high (only 32 pins supported)
  0 or 1 if pin available, depending on pin state

s32 AOUT_DigitalPinSet | ( | u8 | pin,
|  | u8 | value |
| ) |  |  |

This function sets a digital pin of an AOUT module.

Currently only the MAX5225 based MBHP_AOUT module supports two digital pins

Parameters:

  `[in]` | pin | the pin number (0..31)
  `[in]` | value | 0 or 1

Returns:
  -1 if pin number too high (only 32 pins supported)
  0 on success

u32 AOUT_DigitalPinsGet | ( | void |  | ) |

This function returns the state of all digital pins.

Currently only the MAX5225 based MBHP_AOUT module supports two digital pins

Returns:
  a 32bit value which contains the state of all pins

s32 AOUT_DigitalPinsSet | ( | u32 | value | ) |

This function sets all digital pins of an AOUT module.

Currently only the MAX5225 based MBHP_AOUT module supports two digital pins

Parameters:

  `[in]` | value | each pin has a dedicated flag

Returns:
  < 0 on errors

s32 AOUT_IF_Init | ( | u32 | mode | ) |

This function re-initializes the AOUT module, and requests a refresh of all output channels according to the stored values in aout_values

The update will take place once AOUT_Update is called (e.g. from a periodically called task)

Background info: the AOUT_PinSet function only request an update if the output value has been changed (comparison between new and previous value) This improves performance a lot, especially when AOUT values are written periodically from a timer interrupt (see MIDIbox SID and MIDIbox FM)

However, sometimes it is useful to force a refresh, e.g. after a patch change, to ensure that all AOUT channels are up-to-date, because it allows to connect (or exchange) the AOUT module during runtime.

This function is also important after a configuration update, e.g. after a different AOUT interface type has been selected.

Parameters:

  `[in]` | mode | currently only mode 0 supported

Returns:
  < 0 if initialisation failed

Here is the call graph for this function:

const char* AOUT_IfNameGet | ( | aout_if_t | if_type | ) |

s32 AOUT_Init | ( | u32 | mode | ) |

Initializes AOUT driver Should be called from Init() during startup

Parameters:

  `[in]` | mode | currently only mode 0 supported

Returns:
  < 0 if initialisation failed

s32 AOUT_PinGet | ( | u8 | pin | ) |

This function returns the current (target) output value of an output channel.

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)

Returns:
  -1 if pin not available
  >= 0 if pin available (16bit output value)

s32 AOUT_PinPitchGet | ( | u8 | pin | ) |

This function returns the pitch offset of an output channel.

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)

Returns:
  -1 if pin not available
  >= 0 if pin available (signed 16bit output value)

s32 AOUT_PinPitchRangeGet | ( | u8 | pin | ) |

This function returns the pitch range of an output channel.

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)

Returns:
  -1 if pin not available
  >= 0 if pin available (8bit output value)

s32 AOUT_PinPitchRangeSet | ( | u8 | pin,
|  | u8 | value |
| ) |  |  |

This function sets the pitch range for an output channel

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)
  `[in]` | value | the pitch range (0..127) - only values between 2..12 are really useful

Returns:
  -1 if pin not available
  0 on success

Here is the call graph for this function:

s32 AOUT_PinPitchSet | ( | u8 | pin,
|  | s16 | value |
| ) |  |  |

This function sets the pitch offset for an output channel

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)
  `[in]` | value | the pitch (-0x8000..+0x7fff)

Returns:
  -1 if pin not available
  0 on success

Here is the call graph for this function:

s32 AOUT_PinSet | ( | u8 | pin,
|  | u16 | value |
| ) |  |  |

This function sets an output channel to a given 16-bit value.

The output value won't be transfered to the module immediately, but will be buffered instead. By calling AOUT_Update() the requested changes will take place.

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)
  `[in]` | value | the 16bit value

Returns:
  -1 if pin not available
  0 on success

Here is the call graph for this function:

s32 AOUT_PinSlewRateGet | ( | u8 | pin | ) |

This function returns the slew rate of an output channel.

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)

Returns:
  -1 if pin not available
  >= 0 if pin available (8bit output value)

s32 AOUT_PinSlewRateSet | ( | u8 | pin,
|  | u8 | value |
| ) |  |  |

This function sets the slew rate for an output channel

Parameters:

  `[in]` | pin | the pin number (0..AOUT_NUM_CHANNELS-1)
  `[in]` | value | the slew rate (0..255 mS)

Returns:
  -1 if pin not available
  0 on success

s32 AOUT_SuspendGet | ( | void |  | ) |

s32 AOUT_SuspendSet | ( | u8 | suspend | ) |

This function allows to suspend any updates until suspend will be deactived

Parameters:

  `[in]` | suspend | if 1: AOUT_Update() has no effect, if 0: module will be re-initialized via AOUT_IF_Init(0) and AOUT_Update() works again

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 AOUT_TerminalHelp | ( | void * | _output_function | ) |

s32 AOUT_TerminalParseLine | ( | char * | input,
|  | void * | _output_function |
| ) |  |  |

Here is the call graph for this function:

s32 AOUT_TerminalPrintConfig | ( | void * | _output_function | ) |

s32 AOUT_Update | ( | void |  | ) |

Updates the output channels of the connected AOUT module

Should be called, whenever changes have been requested via AOUT_Pin*Set or AOUT_DigitalPin*Set

Returns:
  < 0 on errors

Here is the call graph for this function: