.. _gettingStartedProcessorsTwoDoc:

.. index:: single: Example; Processors

======================================================
Built-In Processors, Constants, and Switches (Part II)
======================================================

Let's improve on our :ref:`previous example <exampleProcessorFixed>` and add level control to the output signal.
	
In the :ref:`previous example <ExampleProcessorFixed>`, the properties of ``Level()`` were fixed. What if we want to bypass the processor using a latching switch connected to digital input 1? Here's how it is done::

	DigitalIn[1] >> LevelSwitch;
	
	# Property assignment to control the behaviour of Level()
	Microphone 
	>> Level (
		gainType:	GainValue
		gain:		3.98
		offset:		0.0
		bypass: 	LevelSwitch
	) 
	>> MainOutput;

We could have also avoided declaring ``LevelSwitch`` and assigned ``DigitalIn[1]`` to ``bypass``::
	
	# Property assignment to control the behaviour of Level()
	Microphone 
	>> Level (
		gainType:	GainValue
		gain:		3.98
		offset:		0.0
		bypass: 	DigitalIn[1]
	) 
	>> MainOutput;

:ref:`DigitalIn_1 <DigitalIn>` is a :ref:`switch block <switchDoc>` declared in the :ref:`platform descriptor file <platformDoc>`. Its input port is connected to a digital input hardware resource. The output port of ``DigitalIn_1`` is of type `boolean` and can connect to the ``bypass`` port of ``gainDB()``.

We could also control the amplification/attenuation level of ``gainDB()`` by physically connecting a potentiometer to analog input 1 on the hardware and running the following program. 

::
	
	#Declare a control block labelled 'GainValue'

	signal GainValue {
		default:	0.0
		rate:		ControlRate
		reset:		MasterReset
		meta:		'Gain level control with potentiometer at analog input 1'
	}
	
	# Connect 'ControlIn[1]' to input of 'GainValue' after value mapping
	ControlIn[1] 
	>> Map (
		mode:		'Linear'
		minimum:	0.0
		maximum:	3.98
		bypass:		off
	)
	>> GainValue;
	
	#Add variables to control the behaviour of gainDB  
	Microphone 
	>> Level (
		gainType:	'Linear'
		gain:		GainValue
		offset:		0.0
		bypass:		LevelSwitch
	)  
	>> MainOutput;

	
:ref:`ControlIn <ControlIn>` is a :ref:`signal block <signalDoc>` declared in the :ref:`platform descriptor file <platformDoc>`. Its input port is connected to an analog input hardware resource. The output port of ``ControlIn[1]`` is of type `control real` and can connect to the ``levelDB`` port of ``gainDB()``.

The values received by the ``input`` port of ``GainValueDB`` from the ``output`` port of ``ControlIn[1]`` are in the +/- 10.0 range. However, we would like to control the ``levelDB`` property of ``gainDB()`` between the values of -96.0 and 6.0 dB. This can be achieved through the ``mapping`` property of a control block by applying a linear transformation.

::

	signal GainValueDB {
		default:	-96.0
		rate:		ControlRate
		reset:		MasterReset
		meta:		'Gain level control with potentiometer at analog input 1'
	}

	ControlIn[1]
	>> Map (
		mode:		'Exponential'
		minimum:	-96.0
		maximum:	12.0
		bypass:		off
	) 
	>> Round (
		mode:		'Truncate'		
		increment:	0.1	
		bypass:		off
	)
	>> GainValueDB;
	
	Microphone 
	>> Level (
		gainType:	'Decibel'
		gain:		GainValueDB
		offset:		0.0
		bypass: 	LevelSwitch
	)  
	>> MainOutput;