MIOS Functions Reference (ASM Version)


Click here for C version


MIOS_MIDI_BeginStream
FUNCTION MIOS_MIDI_BeginStream
DESCRIPTION use this function before a new MIDI event or stream should be sent. Necessary for a correct function of the MIDIbox Link feature!
IN -
OUT -
USES -
EXAMPLE

        ;; send the MIDI event B0 07 7F
        call        MIOS_MIDI_BeginStream
        movlw        0xb0
        call        MIOS_MIDI_TxBufferPut
        movlw        0x07
        call        MIOS_MIDI_TxBufferPut
        movlw        0x7f
        call        MIOS_MIDI_TxBufferPut
        call        MIOS_MIDI_EndStream

Back to the top

MIOS_MIDI_DeviceIDAutoSet
FUNCTION MIOS_MIDI_DeviceIDAutoSet
DESCRIPTION derives the MIDI device ID from the PIC ID header
IN -
OUT -
USES BSR, TBLPTR
EXAMPLE

        ;; set device ID to the specified value in the PIC ID header
        call        MIOS_MIDI_DeviceIDAutoSet

Back to the top

MIOS_MIDI_DeviceIDGet
FUNCTION MIOS_MIDI_DeviceIDGet
DESCRIPTION returns the MIDI device ID
IN -
OUT device number in WREG and MIOS_PARAMETER1 (0x00-0x7f)
USES BSR
EXAMPLE

        ;; print device ID on display
        call        MIOS_MIDI_DeviceIDGet
        call        MIOS_LCD_PrintHex2

Back to the top

MIOS_MIDI_DeviceIDSet
FUNCTION MIOS_MIDI_DeviceIDSet
DESCRIPTION sets the MIDI device ID. Should be a unique number in a MIDI chain. Normaly this ID is derived from the PIC ID header with the MIOS_MIDI_DeviceIDAutoSet function
IN device number in WREG (0x00-0x7f)
OUT -
USES BSR
EXAMPLE

        ;; set device ID to 0x03
        movlw        0x03
        call        MIOS_MIDI_DeviceIDSet

Back to the top

MIOS_MIDI_EndStream
FUNCTION MIOS_MIDI_EndStream
DESCRIPTION use this function after a MIDI event or stream has been sent. Necessary for a correct function of the MIDIbox Link feature!
IN -
OUT -
USES -
EXAMPLE

        ;; send the MIDI event 90 36 7F
        call        MIOS_MIDI_BeginStream
        movlw        0x90
        call        MIOS_MIDI_TxBufferPut
        movlw        0x36
        call        MIOS_MIDI_TxBufferPut
        movlw        0x7f
        call        MIOS_MIDI_TxBufferPut
        call        MIOS_MIDI_EndStream

Back to the top

MIOS_MIDI_Init
FUNCTION MIOS_MIDI_Init
DESCRIPTION initialises the MIDI interface: baudrate will be set depending on To-Host/MIDI option, Rx and Tx buffer will be emptied
IN -
OUT -
USES BSR
Back to the top

MIOS_MIDI_InterfaceAutoSet
FUNCTION MIOS_MIDI_InterfaceAutoSet
DESCRIPTION derives the MIDI interface type and the MBHP_IIC_MIDI module address from the PIC ID header.
To-Host flag: ID Byte 6, Bit 0
MBHP_IIC_MIDI module address: ID Byte 5
If the slave address is != 0x00 and != 0xff, it will be taken as default MIDI Out by MIOS
IN -
OUT -
USES BSR, TBLPTR
EXAMPLE

        ;; set MIDI interface to the specified type in the PIC ID header
        call        MIOS_MIDI_InterfaceAutoSet

Back to the top

MIOS_MIDI_InterfaceGet
FUNCTION MIOS_MIDI_InterfaceGet
DESCRIPTION returns the current MIDI interface type following Interface types are provided:
0x00: MIOS_MIDI_INTERFACE_COMMON (common MIDI interface, 31250 baud)
0x01: MIOS_MIDI_INTERFACE_TO_HOST (MIDIbox-to-COM interface, RS232, 38400 baud)
>= 0x02: MBHP_IIC_MIDI module address
IN -
OUT interface type in WREG and MIOS_PARAMETER1
USES BSR
EXAMPLE

        ;; branch if MBHP_IIC_MIDI module is selected
        call        MIOS_MIDI_InterfaceGet
        andlw   0xfe
        bnz     HandleExternalMIDI

Back to the top

MIOS_MIDI_InterfaceSet
FUNCTION MIOS_MIDI_InterfaceSet
DESCRIPTION this function has two purposes:
If the interface number is 0x00 or 0x01, the internal USART will be selected, and a baudrate of either 31250 or 38400 baud will be configured:
0x00: MIOS_MIDI_INTERFACE_COMMON (common MIDI interface, 31250 baud)
0x01: MIOS_MIDI_INTERFACE_TO_HOST (MIDIbox-to-COM interface, RS232, 38400 baud)

With values >= 0x02 a MBHP_IIC_MIDI module will be selected for outgoing MIDI messages (which are sent with MIOS_MIDI_TxBufferPut)
Incoming messages are still handled with the internal USART!
If data should be received from a MBHP_IIC_MIDI module, please use the appr. functions of the software package which is provided together with the module.
Note that the MIOS_MIDI_InterfaceAutoSet function allows you to derive the MIDI interface type and the IIC slave address from the PIC ID header!
IN interface type in WREG
OUT -
USES BSR
EXAMPLE

        ;; send MIDI clock over internal MIDI Out with normal baudrate
        movlw        MIOS_MIDI_INTERFACE_COMMON
        call        MIOS_MIDI_InterfaceSet

        movlw        0xf8  ; (MIDI Clock)
        call        MIOS_MIDI_TxBufferPut

        ;; send MIDI clock over MBHP_IIC_MIDI with address 0x10
        movlw        0x10
        call        MIOS_MIDI_InterfaceSet

        movlw        0xf8  ; (MIDI Clock)
        call        MIOS_MIDI_TxBufferPut

        ;; switch back to the default interface
        call        MIOS_MIDI_InterfaceAutoSet

Back to the top

MIOS_MIDI_MergerGet
FUNCTION MIOS_MIDI_MergerGet
DESCRIPTION returns configuration of integrated MIDI merger: 0x00: MIOS_MIDI_MERGER_DISABLED (merger disabled)
0x01: MIOS_MIDI_MERGER_ENABLED (merger enabled)
0x02: MIOS_MIDI_MERGER_MBLINK_EP (MIDIbox Link End Point)
0x03: MIOS_MIDI_MERGER_MBLINK_FP (MIDIbox Link Forwarding Point)
IN -
OUT merger function ID in WREG and MIOS_PARAMETER1
USES -
EXAMPLE

        ;; get current merger configuration and branch depending on setting
        call        MIOS_MIDI_MergerGet
        BRA_IFSET WREG, 1, ACCESS, MBLinkEnabled
        rgoto        MBLinkNotEnabled

Back to the top

MIOS_MIDI_MergerSet
FUNCTION MIOS_MIDI_MergerSet
DESCRIPTION configures the integrated MIDI merger following Merger IDs are provided:
0x00: MIOS_MIDI_MERGER_DISABLED (merger disabled)
0x01: MIOS_MIDI_MERGER_ENABLED (merger enabled)
0x02: MIOS_MIDI_MERGER_MBLINK_EP (MIDIbox Link End Point)
0x03: MIOS_MIDI_MERGER_MBLINK_FP (MIDIbox Link Forwarding Point)
IN merger function ID in WREG
OUT -
USES -
EXAMPLE

        ;; configure the MIDIbox as MIDIbox Link End Point
        ;; (means: merger enabled only for events which has
        ;; been generated by another MIDIbox which is configured
        ;; as MIDIbox Link Forwarding Point)
        movlw        MIOS_MIDI_MERGER_MBLINK_EP
        call        MIOS_MIDI_MergerSet

Back to the top

MIOS_MIDI_RxBufferFree
FUNCTION MIOS_MIDI_RxBufferFree
DESCRIPTION returns number of free bytes in receive buffer
IN -
OUT number of free bytes in WREG
USES BSR
NOTE this function is for internal use within MIOS only!
Received bytes will be notified by the MPROC hooks!
EXAMPLE

        ;; put a MIDI byte into the Rx Buffer if it isn't full
        call        MIOS_MIDI_RxBufferFree
        bz        BufferIsFull
        movlw        0xf8        ; (MIDI Clock)
        call        MIOS_MIDI_RxBufferPut

Back to the top

MIOS_MIDI_RxBufferGet
FUNCTION MIOS_MIDI_RxBufferGet
DESCRIPTION gets a byte from the receive buffer
IN -
OUT received byte in WREG
USES BSR, FSR1
NOTE this function is for internal use within MIOS only!
Received bytes will be notified by the MPROC hooks!
EXAMPLE

        ;; get a MIDI byte from the Rx Buffer if something has been received
        call        MIOS_MIDI_RxBufferUsed
        bz        NothingReceived
        call        MIOS_MIDI_RxBufferGet

Back to the top

MIOS_MIDI_RxBufferPut
FUNCTION MIOS_MIDI_RxBufferPut
DESCRIPTION puts a byte onto the receive buffer
IN byte in WREG
OUT -
USES BSR, FSR1
NOTE this function is for internal use within MIOS only!
Received bytes will be notified by the MPROC hooks!
EXAMPLE

        ;; put a MIDI byte into the Rx Buffer if it isn't full
        call        MIOS_MIDI_RxBufferFree
        bz        BufferIsFull
        movlw        0xf8        ; (MIDI Clock)
        call        MIOS_MIDI_RxBufferPut

Back to the top

MIOS_MIDI_RxBufferUsed
FUNCTION MIOS_MIDI_RxBufferUsed
DESCRIPTION returns number of used bytes in receive buffer
IN -
OUT number of used bytes in WREG
USES BSR
NOTE this function is for internal use within MIOS only!
Received bytes will be notified by the MPROC hooks!
EXAMPLE

        ;; branch if something has been received via MIDI
        call        MIOS_MIDI_RxBufferUsed
        bz        ReceivedSomething

Back to the top

MIOS_MIDI_TxBufferFlush
FUNCTION MIOS_MIDI_TxBufferFlush
DESCRIPTION waits until all MIDI bytes in the Tx buffer have been transmitted
IN -
OUT -
USES BSR, FSR1
EXAMPLE

        ;; wait until buffer is empty, thereafter send a bunch of new bytes
        call        MIOS_MIDI_TxBufferFlush
        movlw        0xf0
        call        MIOS_MIDI_TxBufferPut
        ;;  ...

Back to the top

MIOS_MIDI_TxBufferFree
FUNCTION MIOS_MIDI_TxBufferFree
DESCRIPTION returns number of free bytes in transmit buffer
IN -
OUT number of free bytes in WREG
USES BSR
NOTE this function is for internal use within MIOS only!
The MIOS_MIDI_TxBufferPut() function will wait if the buffer is full.
EXAMPLE

        ;; put a MIDI byte into the Tx Buffer if it isn't full
        call        MIOS_MIDI_TxBufferFree
        bz        BufferIsFull
        movlw        0xf8        ; (MIDI Clock)
        call        MIOS_MIDI_TxBufferPut

Back to the top

MIOS_MIDI_TxBufferGet
FUNCTION MIOS_MIDI_TxBufferGet
DESCRIPTION gets a byte from the transmit buffer
IN -
OUT byte to be transmitted in WREG
USES BSR, FSR1
NOTE this function is for internal use within MIOS only!
EXAMPLE

        ;; get a MIDI byte from the Tx Buffer if new byte is available
        call        MIOS_MIDI_TxBufferUsed
        bz        NoByteAvailable
        call        MIOS_MIDI_TxBufferGet

Back to the top

MIOS_MIDI_TxBufferPut
FUNCTION MIOS_MIDI_TxBufferPut
DESCRIPTION puts a byte onto the transmit buffer.
If Tx buffer is full, the function will be suspended until one byte has been transmitted via MIDI.
This function redirects outgoing bytes to the MBHP_IIC_MIDI module if it has been selected with the MIOS_MIDI_InterfaceSet or MIOS_MIDI_InterfaceAutoSet function
IN byte in WREG
OUT -
USES BSR, FSR1
EXAMPLE

        ;; put a MIDI byte into the Tx Buffer if it isn't full
        movlw        0xf8        ; (MIDI Clock)
        call        MIOS_MIDI_TxBufferPut

Back to the top

MIOS_MIDI_TxBufferUsed
FUNCTION MIOS_MIDI_TxBufferUsed
DESCRIPTION returns number of used bytes in buffer
IN -
OUT number of used bytes in WREG
USES BSR
NOTE this function is for internal use within MIOS only!
The MIOS_MIDI_TxBufferPut() function will wait if the buffer is full.
EXAMPLE

        ;; branch if something has been put into the Tx Buffer
        call        MIOS_MIDI_TxBufferUsed
        bz        GotSomething

Back to the top

MIOS_MPROC_MergerDisable
FUNCTION MIOS_MPROC_MergerDisable
DESCRIPTION this function allows you to temporary disable the MIDI merger processing during receiving a new event. It's used by SysEx parsers to prevent the forwarding of SysEx strings, but can also used by the USER_MPROC_NotifyReceivedByte hook to filter other events The merger will be enabled again after a complete MIDI event has been received!
IN -
OUT -
USES BSR
Back to the top

MIOS_MPROC_MergerEnable
FUNCTION MIOS_MPROC_MergerEnable
DESCRIPTION enables MIDI merger processing like specified with MIOS_MIDI_MergerSet
IN -
OUT -
USES BSR
Back to the top

MIOS_MPROC_MergerGet
FUNCTION MIOS_MPROC_MergerGet
DESCRIPTION returns 1 if merger processing is enabled, 0 if disabled
IN -
OUT status in WREG and MIOS_PARAMETER1
USES BSR
Back to the top

MIOS_AIN_DeadbandGet
FUNCTION MIOS_AIN_DeadbandGet
DESCRIPTION returns the difference between last and current pot value which has to be achieved to trigger the "NotifyChange" function
IN -
OUT diff value in MIOS_PARAMETER1 and WREG
USES BSR
Back to the top

MIOS_AIN_DeadbandSet
FUNCTION MIOS_AIN_DeadbandSet
DESCRIPTION sets the difference between last and current pot value which has to be achieved to trigger the "NotifyChange" function
IN deadband value in WREG
OUT -
USES BSR
Back to the top

MIOS_AIN_DynamicPrioGet
FUNCTION MIOS_AIN_DynamicPrioGet
DESCRIPTION returns the status of the dynamic priority sampling feature. The flag will only be taken into account in multiplexed mode (more than 8 pots connected to the core module via AINX4). If active, the sampling frequency of the two last turned pots will be dynamically increased for a better accuracy.
IN -
OUT WREG = 0x00: dynamic priority sampling disabled or non-multiplexed mode active
WREG = 0x01: dynamic priority sampling enabled (default)
USES BSR
Back to the top

MIOS_AIN_DynamicPrioSet
FUNCTION MIOS_AIN_DynamicPrioSet
DESCRIPTION enables or disables the dynamic priority sampling feature. The flag will only be taken into account in multiplexed mode (more than 8 pots connected to the core module via AINX4). If active, the sampling frequency of the two last turned pots will be dynamically increased for a better accuracy.
IN WREG = 0x00: dynamic priority sampling disabled
WREG = 0x01: dynamic priority sampling enabled (default)
OUT -
USES BSR
Back to the top

MIOS_AIN_LastPinsGet
FUNCTION MIOS_AIN_LastPinsGet
DESCRIPTION returns the index of the two pins which have been sampled with a different value at last.
In less abstract words: returns the number of the last two turned pots.
IN -
OUT WREG and MIOS_PARAMETER1: last pin
MIOS_PARAMETER2: last but one pin
USES BSR
Back to the top

MIOS_AIN_Muxed
FUNCTION MIOS_AIN_Muxed
DESCRIPTION enables the MUX mode (up to 64 pots can be connected via AIN multiplexers
IN -
OUT -
USES BSR
Back to the top

MIOS_AIN_NumberGet
FUNCTION MIOS_AIN_NumberGet
DESCRIPTION returns number of available analog pins
IN -
OUT number of analog pins in MIOS_PARAMETER1 and WREG
USES BSR
Back to the top

MIOS_AIN_NumberSet
FUNCTION MIOS_AIN_NumberSet
DESCRIPTION sets number of available AIN pins
If number > 64, value will be forced to 64
IN number of analog pins in WREG
OUT -
USES BSR
Back to the top

MIOS_AIN_Pin7bitGet
FUNCTION MIOS_AIN_Pin7bitGet
DESCRIPTION returns 7-bit value of AIN input
IN number of analog input pin in WREG
OUT 7-bit value in MIOS_PARAMETER1 and WREG
USES BSR, FSR1, MIOS_PARAMETER[12]
Back to the top

MIOS_AIN_PinGet
FUNCTION MIOS_AIN_PinGet
DESCRIPTION returns value of AIN input
IN pin number in WREG
OUT MSB in MIOS_PARAMETER2, LSB in MIOS_PARAMETER1 and WREG
USES FSR1
Back to the top

MIOS_AIN_PinLSBGet
FUNCTION MIOS_AIN_PinLSBGet
DESCRIPTION returns LSB value of AIN input
IN pin number in WREG
OUT LSB value in MIOS_PARAMETER1 and WREG
USES FSR1
Back to the top

MIOS_AIN_PinMSBGet
FUNCTION MIOS_AIN_PinMSBGet
DESCRIPTION returns MSB value of AIN input
IN pin number in WREG
OUT MSB value in MIOS_PARAMETER1 and WREG
USES FSR1
Back to the top

MIOS_AIN_UnMuxed
FUNCTION MIOS_AIN_UnMuxed
DESCRIPTION disables the MUX mode (8 pots can be connected directly to the analog input pins of the PIC
IN -
OUT -
USES BSR
Back to the top

MIOS_MF_DeadbandGet
FUNCTION MIOS_MF_DeadbandGet
DESCRIPTION returns the deadband value for MF driver
IN -
OUT deadband value in MIOS_PARAMETER1 and WREG
USES BSR
Back to the top

MIOS_MF_DeadbandSet
FUNCTION MIOS_MF_DeadbandSet
DESCRIPTION sets the deadband value for MF driver
IN deadband value in WREG
OUT -
USES BSR
NOTE function can only be used when motordriver has been enabled.
Back to the top

MIOS_MF_Disable
FUNCTION MIOS_MF_Disable
DESCRIPTION disables the MF module
IN -
OUT -
USES BSR
Back to the top

MIOS_MF_Enable
FUNCTION MIOS_MF_Enable
DESCRIPTION enables the MF module - in this mode, multiplexers are disabled. Up to 8 motorfaders can be controlled over the MUX port. This function can only be used when the motordriver has been enabled.
IN -
OUT -
USES BSR
EXAMPLE

        ;; initialize the MF driver for Alps RSAON11M9 faders
        call        MIOS_MF_Enable
        movlw        3
        call        MIOS_MF_DeadbandSet

        movlw        1
        call        MIOS_MF_PWM_DutyCycleUpSet
        movlw        1
        call        MIOS_MF_PWM_DutyCycleDownSet
        movlw        3
        call        MIOS_MF_PWM_PeriodSet

Back to the top

MIOS_MF_FaderMove
FUNCTION MIOS_MF_FaderMove
DESCRIPTION set target position and move fader
IN fader number in WREG, fader position in MIOS_PARAMETER[12]
OUT -
USES FSR1, BSR
NOTE function can only be used when motordriver has been enabled.
EXAMPLE
        ;; move fader #7 to highest position (0x3ff)
        movlw        0x03
        movwf        MIOS_PARAMETER2
        movlw        0xff
        movwf        MIOS_PARAMETER1
        movlw        0x07
        call        MIOS_MF_FaderMove
Back to the top

MIOS_MF_PWM_DutyCycleDownGet
FUNCTION MIOS_MF_PWM_DutyCycleDownGet
DESCRIPTION Returns the Duty Cycle for downward moves - see http://www.ucapps.de/mbhp_mf.html for detailed informations about this value
IN -
OUT Duty Cycle in WREG
USES BSR
Back to the top

MIOS_MF_PWM_DutyCycleDownSet
FUNCTION MIOS_MF_PWM_DutyCycleDownSet
DESCRIPTION Sets the Duty Cycle for downward moves - see http://www.ucapps.de/mbhp_mf.html for detailed informations about this value
IN Duty Cycle in WREG
OUT -
USES BSR
Back to the top

MIOS_MF_PWM_DutyCycleUpGet
FUNCTION MIOS_MF_PWM_DutyCycleUpGet
DESCRIPTION Returns the Duty Cycle for upward moves - see http://www.ucapps.de/mbhp_mf.html for detailed informations about this value
IN -
OUT Duty Cycle in WREG
USES BSR
Back to the top

MIOS_MF_PWM_DutyCycleUpSet
FUNCTION MIOS_MF_PWM_DutyCycleUpSet
DESCRIPTION Sets the Duty Cycle for upward moves - see http://www.ucapps.de/mbhp_mf.html for detailed informations about this value
IN Duty Cycle in WREG
OUT -
USES BSR
Back to the top

MIOS_MF_PWM_PeriodGet
FUNCTION MIOS_MF_PWM_PeriodGet
DESCRIPTION Returns the PWM period - see http://www.ucapps.de/mbhp_mf.html for detailed informations about this value
IN -
OUT PWM period in WREG
USES BSR
Back to the top

MIOS_MF_PWM_PeriodSet
FUNCTION MIOS_MF_PWM_PeriodSet
DESCRIPTION Sets the PWM period - see http://www.ucapps.de/mbhp_mf.html for detailed informations about this value
IN PWM period in WREG
OUT -
USES BSR
Back to the top

MIOS_MF_SuspendDisable
FUNCTION MIOS_MF_SuspendDisable
DESCRIPTION deactivate suspend mode of motor
(function used by touchsensor detection)
function can only be used when motordriver has been enabled.
IN number of motor in WREG (0-7)
OUT -
USES BSR, FSR1
Back to the top

MIOS_MF_SuspendEnable
FUNCTION MIOS_MF_SuspendEnable
DESCRIPTION suspends the motor
(function used by touchsensor detection)
function can only be used when motordriver has been enabled.
IN number of motor in WREG (0-7)
OUT -
USES BSR
Back to the top

MIOS_MF_SuspendGet
FUNCTION MIOS_MF_SuspendGet
DESCRIPTION return suspend state of motor
IN number of motor in WREG (0-7)
OUT WREG = 1 if motor is suspended, else 0
USES BSR
Back to the top

MIOS_MF_TouchDetectionReset
FUNCTION MIOS_MF_TouchDetectionReset
DESCRIPTION this function resets the software implemented touch detection so that the fader is repositioned regardless if it is currently manually moved or not
IN number of motor in WREG (0-7)
OUT -
USES BSR
Back to the top

MIOS_DIN_PinAutoRepeatDisable
FUNCTION MIOS_DIN_PinAutoRepeatDisable
DESCRIPTION disables the auto-repeat feature for the appr. pin
IN number of pin in WREG
OUT -
USES FSR1
Back to the top

MIOS_DIN_PinAutoRepeatEnable
FUNCTION MIOS_DIN_PinAutoRepeatEnable
DESCRIPTION enables the auto-repeat feature for the appr. pin
IN number of pin in WREG
OUT -
USES FSR1
Back to the top

MIOS_DIN_PinAutoRepeatGet
FUNCTION MIOS_DIN_PinAutoRepeatGet
DESCRIPTION returns != 0 if auto-repeat has been enabled for the appr. pin
IN number of pin in WREG
OUT WREG != 0 if auto-repeat has been enabled for this pin
WREG == 0 if auto-repeat has been disabled for this pin
USES FSR1
Back to the top

MIOS_DIN_PinGet
FUNCTION MIOS_DIN_PinGet
DESCRIPTION returns value from a DIN Pin
IN Pin number in WREG
OUT 1 if pin is +5V, 0 if pin is 0V in MIOS_PARAMETER and WREG
USES FSR1 and BSR
Back to the top

MIOS_DIN_SRGet
FUNCTION MIOS_DIN_SRGet
DESCRIPTION returns value of DIN shift register
IN number of shift register in WREG
OUT value of shift register in MIOS_PARAMETER1 and WREG,
pointer to shift register in FSR1
USES FSR1
Back to the top

MIOS_DOUT_PinGet
FUNCTION MIOS_DOUT_PinGet
DESCRIPTION returns value from a DOUT Pin
IN Pin number in MIOS_PARAMETER1 and WREG
OUT 1 if pin is +5V, 0 if pin is 0V
USES FSR1 and BSR
Back to the top

MIOS_DOUT_PinSet
FUNCTION MIOS_DOUT_PinSet
DESCRIPTION set pin to 0 or 5V
IN Pin number in WREG, value in MIOS_PARAMETER1
USES FSR1 and BSR
Back to the top

MIOS_DOUT_PinSet0
FUNCTION MIOS_DOUT_PinSet0
DESCRIPTION set pin to 0V
IN Pin number in WREG
USES FSR1 and BSR
Back to the top

MIOS_DOUT_PinSet1
FUNCTION MIOS_DOUT_PinSet1
DESCRIPTION set pin to 5V
IN Pin number in WREG
USES FSR1 and BSR
Back to the top

MIOS_DOUT_SRGet
FUNCTION MIOS_DOUT_SRGet
DESCRIPTION returns value of DOUT shift register
IN number of shift register in WREG
OUT value of shift register in WREG and MIOS_PARAMETER1,
pointer to shift register in FSR1
USES FSR1 and BSR
Back to the top

MIOS_DOUT_SRSet
FUNCTION MIOS_DOUT_SRSet
DESCRIPTION sets value of DOUT shift register
IN number of shift register in WREG
value in MIOS_PARAMETER1
OUT pointer to shift register in FSR1
USES FSR1 and BSR
Back to the top

MIOS_ENC_Abs7bitAdd
FUNCTION MIOS_ENC_Abs7bitAdd
DESCRIPTION adds the incrementer to the absolute 7-bit value of encoder
This function saturates the value. That means: if the resulting value is greater than 127, it will be saturated to 127. The same will be done when the value is less than 0
IN encoder number in WREG,
incrementer value in MIOS_PARAMETER1
OUT returns new absolute value in WREG and MIOS_PARAMETER1
MIOS_PARAMETER2[0] is 1, if the value has been changed, 0 if it
is equal to the old value
USES BSR, FSR1, TBLPTR
NOTE This function uses a spare register which is only available when the encoder speed is set to MIOS_ENC_SPEED_NORMAL. In all other speed modes (MIOS_ENC_SPEED_SLOW and MIOS_ENC_SPEED_FAST) this function should NOT be used, instead a dedicated handler for absolute values should be written in this case (see enc_example* applications)
EXAMPLE

        ;; subtract -5 from the 7-bit value of encoder #0
        movlw        -5                        ; store incrementer in MIOS_PARAMETER1
        movwf        MIOS_PARAMETER1
        movlw        0x00                        ; add this value for encoder #0
        call        MIOS_ENC_Abs7bitAdd

Back to the top

MIOS_ENC_Abs7bitGet
FUNCTION MIOS_ENC_Abs7bitGet
DESCRIPTION returns absolute 7-bit value of encoder
IN encoder number in WREG
OUT absolute value in WREG and MIOS_PARAMETER1
USES BSR, FSR1, TBLPTR
NOTE This function uses a spare register which is only available when the encoder speed is set to MIOS_ENC_SPEED_NORMAL. In all other speed modes (MIOS_ENC_SPEED_SLOW and MIOS_ENC_SPEED_FAST) this function should NOT be used, instead a dedicated handler for absolute values should be written in this case (see enc_example* applications)
EXAMPLE

        ;; get the current 7-bit value of encoder #0
        movlw        0x00
        call        MIOS_ENC_Abs7bitGet

Back to the top

MIOS_ENC_Abs7bitSet
FUNCTION MIOS_ENC_Abs7bitSet
DESCRIPTION sets the absolute 7-bit value of encoder
IN encoder number in WREG, absolute value in MIOS_PARAMETER1
OUT -
USES BSR, FSR1, TBLPTR
NOTE This function uses a spare register which is only available when the encoder speed is set to MIOS_ENC_SPEED_NORMAL. In all other speed modes (MIOS_ENC_SPEED_SLOW and MIOS_ENC_SPEED_FAST) this function should NOT be used, instead a dedicated handler for absolute values should be written in this case (see enc_example* applications)
EXAMPLE

        ;; set the 7-bit value of encoder #0 to 0x40
        movlw        0x40                        ; store value in MIOS_PARAMETER1
        movwf        MIOS_PARAMETER1
        movlw        0x00                        ; set this value for encoder #0
        call        MIOS_ENC_Abs7bitSet

Back to the top

MIOS_ENC_NumberGet
FUNCTION MIOS_ENC_NumberGet
DESCRIPTION returns the number of encoders which have been defined in the encoder table
IN -
OUT number of encoders in WREG and MIOS_PARAMETER1
USES FSR1, TBLPTR
Back to the top

MIOS_ENC_SpeedGet
FUNCTION MIOS_ENC_SpeedGet
DESCRIPTION returns the speed setting for an encoder
following settings are available:
MIOS_ENC_SPEED_SLOW 0x00
MIOS_ENC_SPEED_NORMAL 0x01
MIOS_ENC_SPEED_FAST 0x02
IN encoder number in WREG
OUT speed mode in WREG and MIOS_PARAMETER1
speed parameter in MIOS_PARAMETER2
USES BSR, FSR1, TBLPTR
EXAMPLE

        ;; return the speed setting of encoder #0
        movlw        0x00
        call        MIOS_ENC_SpeedGet

Back to the top

MIOS_ENC_SpeedSet
FUNCTION MIOS_ENC_SpeedSet
DESCRIPTION sets the speed for an encoder
following settings are available:
MIOS_ENC_SPEED_SLOW 0x00 (requires additional parameter)
MIOS_ENC_SPEED_NORMAL 0x01 (no additional parameter)
MIOS_ENC_SPEED_FAST 0x02 (requires additional parameter)
IN encoder number in WREG,
speed mode in MIOS_PARAMETER1
speed parameter in MIOS_PARAMETER2
OUT -
USES BSR, FSR1, TBLPTR
NOTE When using MIOS_ENC_SPEED_SLOW or MIOS_ENC_SPEED_FAST, the MIOS_ENC_Abs* functions are not available since these speed modes allocate a spare register which is normaly used to store the absolute value. So, in this case a dedicated handler for absolute values should be written (see enc_example* applications)
EXAMPLE

  MIOS_ENC_SPEED_NORMAL
  ~~~~~~~~~~~~~~~~~~~~~
        ;; this speed mode requires no additional parameter

        ;; set speed of encoder #0 to "normal"
        movlw        MIOS_ENC_SPEED_NORMAL        ; normal speed mode
        movwf        MIOS_PARAMETER1
        movlw        0x00                        ; rotary encoder #0
        call        MIOS_ENC_SpeedSet

  MIOS_ENC_SPEED_SLOW
  ~~~~~~~~~~~~~~~~~~~
        ;; this speed mode allows to define a predivider value
        ;; from 0 to 7 which has to be specified in
        ;; MIOS_PARAMETER2

        ;; set speed for encoder #0 to "slow", use a predivider
        ;; of 3 so that the encoder will increment every 4th
        ;; step
        movlw        0x03                        ; predivider value (- 1)
        movwf        MIOS_PARAMETER2
        movlw        MIOS_ENC_SPEED_SLOW        ; slow speed mode
        movwf        MIOS_PARAMETER1
        movlw        0x00                        ; rotary encoder #0
        call        MIOS_ENC_SpeedSet

  MIOS_ENC_SPEED_FAST
  ~~~~~~~~~~~~~~~~~~~
        ;; in this speed mode the increment value depends on the
        ;; rotational speed based on the following formula:

        ;;    speed_ctr: decremented with every update cycle
        ;;    (-> MIOS_SRIO_UpdateFrqSet)
        ;;                 (normaly 1 ms) to measure the time between
        ;;                 two encoder steps
        ;;                 Init value: 0x7f
        ;;                 reaches 0x00 after 127 update cycles
        ;;                (normaly after 127 ms)
        ;;    MIOS_PARAMETER2: specified with the MIOS_ENC_SpeedSet
        ;;
        ;;                       function, allowed values:
        ;;                          0 (fast)     -> divider = 2^(7-0) = 128
        ;;                          1 (faster)   -> divider = 2^(7-1) =  64
        ;;                          ...
        ;;                          7 (fastest)  -> divider = 2^(7-7) =        1
        ;; ->
        ;;    incrementer = speed_ctr / (2^(7-MIOS_PARAMETER2))

        ;; set speed for encoder #0 to "fast", speed exponent value is 2
        movlw        0x02                        ; speed exponent
        movwf        MIOS_PARAMETER2
        movlw        MIOS_ENC_SPEED_FAST        ; fast speed mode
        movwf        MIOS_PARAMETER1
        movlw        0x00                        ; rotary encoder #0
        call        MIOS_ENC_SpeedSet

Back to the top

MIOS_SRIO_DebounceGet
FUNCTION MIOS_SRIO_DebounceGet
DESCRIPTION returns the debounce counter reload value of the DIN SR registers
IN -
OUT debounce counter reload value in WREG and MIOS_PARAMETER1
USES BSR
Back to the top

MIOS_SRIO_DebounceSet
FUNCTION MIOS_SRIO_DebounceSet
DESCRIPTION sets the debounce counter reload value for the DIN SR registers which are not assigned to rotary encoders to debounce low-quality buttons.

Debouncing is realized in the following way: on every button movement the debounce preload value will be loaded into the debounce counter register. The counter will be decremented on every SRIO update cycle. So long as this counter isn't zero, button changes will still be recorded, but they won't trigger the USER_DIN_NotifyToggle function.

No (intended) button movement will get lost, but the latency will be increased. Example: if the update frequency is set to 1 mS, and the debounce value to 32, the first button movement will be regognized with a worst-case latency of 1 mS. Every additional button movement which happens within 32 mS will be regognized within a worst-case latency of 32 mS. After the debounce time has passed, the worst-case latency is 1 mS again.

Note that in MIOS versions below v1.9c, the debounce counter also affected the rotary encoders and DOUT registers (they where not serviced).
With MIOS V1.9c and higher, this problem doesn't exist anymore and the debouncing feature can be used in nearly all applications.
Only exception: if the application should record pin changes from digital sensors which are switching very fast, then debouncing should be ommited.
IN debounce counter reload value in WREG
OUT -
USES BSR
Back to the top

MIOS_SRIO_NumberGet
FUNCTION MIOS_SRIO_NumberGet
DESCRIPTION returns number of available SR registers
IN -
OUT number of SRs in MIOS_PARAMETER1 and WREG
USES BSR
Back to the top

MIOS_SRIO_NumberSet
FUNCTION MIOS_SRIO_NumberSet
DESCRIPTION sets number of available SR registers If number > 16, value will be forced to 16
IN number of SRs in WREG
OUT -
USES BSR
Back to the top

MIOS_SRIO_TS_SensitivityGet
FUNCTION MIOS_SRIO_TS_SensitivityGet
DESCRIPTION returns the touchsensor sensitivity
IN -
OUT sensitivity value in MIOS_PARAMETER1 and WREG
USES BSR
Back to the top

MIOS_SRIO_TS_SensitivitySet
FUNCTION MIOS_SRIO_TS_SensitivitySet
DESCRIPTION sets the touch sensor sensitivity.
sensitivity == 0x00 disables the TS so that Pin RD.4 (J14 of the core module) won't be driven by MIOS anymore and therefore is free for other purposes
IN sensitivity value in WREG
OUT -
USES BSR
Back to the top

MIOS_SRIO_UpdateFrqGet
FUNCTION MIOS_SRIO_UpdateFrqGet
DESCRIPTION returns the update frequency of SR registers
IN -
OUT update frequency (unit: milliseconds) in MIOS_PARAMETER1 and WREG
USES BSR
Back to the top

MIOS_SRIO_UpdateFrqSet
FUNCTION MIOS_SRIO_UpdateFrqSet
DESCRIPTION sets the update frequency of SR registers
IN update frequency (unit: milliseconds) in WREG
OUT -
USES BSR
Back to the top

MIOS_LCD_Clear
FUNCTION MIOS_LCD_Clear
DESCRIPTION clears the LCD screen
IN -
OUT -
USES BRS, TBLPTR
EXAMPLE
        ;; clear LCD and print a character
        call    MIOS_LCD_Clear
        movlw   'A'
        call    MIOS_LCD_PrintChar
Back to the top

MIOS_LCD_Cmd
FUNCTION MIOS_LCD_Cmd
DESCRIPTION sends a command to the LCD display
IN command which should be sent in WREG
OUT -
USES BRS, TBLPTR
Back to the top

MIOS_LCD_CursorGet
FUNCTION MIOS_LCD_CursorGet
DESCRIPTION returns the text cursor position
0x00-0x3f: first line
0x40-0x7f: second line
0x80-0xbf: third line or second LCD (if available)
0xc0-0xff: fourth line or second LCD (if available)
IN -
OUT text cursor position in WREG and MIOS_PARAMETER1
USES BRS, TBLPTR
Back to the top

MIOS_LCD_CursorSet
FUNCTION MIOS_LCD_CursorSet
DESCRIPTION sets the text cursor on LCD screen
0x00-0x3f: first line
0x40-0x7f: second line
0x80-0xbf: third line or second LCD (see MIOS_LCD_YAddressSet)
0xc0-0xff: fourth line or second LCD (see MIOS_LCD_YAddressSet)
IN -
OUT -
USES BRS, TBLPTR
EXAMPLE
        ;; print char at first line, first column
        movlw   0x00 + 0
        call    MIOS_LCD_CursorSet
        movlw   'A'
        call    MIOS_LCD_PrintChar

        ;; print char at second line, last column (2x16 LCD)
        movlw   0x40 + 15
        call    MIOS_LCD_CursorSet
        movlw   'B'
        call    MIOS_LCD_PrintChar

        ;; print chars on second LCD
        ;; (or 3rd and 4th line, see see MIOS_LCD_YAddressSet)
        movlw   0x80 + 0
        call    MIOS_LCD_CursorSet
        movlw   'C'
        call    MIOS_LCD_PrintChar

        movlw   0xc0 + 15
        call    MIOS_LCD_CursorSet
        movlw   'D'
        call    MIOS_LCD_PrintChar

Back to the top

MIOS_LCD_Data
FUNCTION MIOS_LCD_Data
DESCRIPTION sends a data value to the LCD display
IN data which should be sent in WREG
OUT -
USES BRS, TBLPTR
Back to the top

MIOS_LCD_Init
FUNCTION MIOS_LCD_Init
DESCRIPTION initializes the LCD display this function is called automatically after startup
IN -
OUT -
USES BRS, TBLPTR
Back to the top

MIOS_LCD_MessageStart
FUNCTION MIOS_LCD_MessageStart
DESCRIPTION a replacement for MIOS_LCD_PrintMessage which allows to start a message without calling "MIOS_LCD_PrintString"
IN message delay in WREG
OUT -
USES BSR
EXAMPLE
        ;; don't invoke DISPLAY_Tick for 2 seconds
        movlw        255
        call        MIOS_LCD_MessageStart
Back to the top

MIOS_LCD_MessageStop
FUNCTION MIOS_LCD_MessageStop
DESCRIPTION this function allows to stop the message immediately so that MIOS_LCD_Tick will be called again
IN -
OUT -
USES BSR
EXAMPLE
        ;; stop message immediately and invoke DISPLAY_Tick again
        call        MIOS_LCD_MessageStop
Back to the top

MIOS_LCD_PrintBCD1
FUNCTION MIOS_LCD_PrintBCD1
DESCRIPTION prints a 8-bit as BCD (decimal value) -- one digit only
IN Value in WREG
OUT one digit on LCD
USES BSR
EXAMPLE
        ;; print leftmost digit of TMP1 on screen
        movf    TMP1, W
        call        MIOS_LCD_PrintBCD1
Back to the top

MIOS_LCD_PrintBCD2
FUNCTION MIOS_LCD_PrintBCD2
DESCRIPTION prints a 8-bit as BCD (decimal value) -- two digits only
IN Value in WREG
OUT two digits on LCD
USES BSR, MIOS_PARAMETER[123]
EXAMPLE
        ;; print two leftmost digits of TMP1 on screen
        movf    TMP1, W
        call        MIOS_LCD_PrintBCD2
Back to the top

MIOS_LCD_PrintBCD3
FUNCTION MIOS_LCD_PrintBCD3
DESCRIPTION prints a 8-bit as BCD (decimal value) -- all three digits
IN Value in WREG
OUT three digits on LCD
USES BSR, MIOS_PARAMETER[123]
EXAMPLE
        ;; print all three digits of TMP1 on screen
        movf    TMP1, W
        call        MIOS_LCD_PrintBCD3
Back to the top

MIOS_LCD_PrintBCD4
FUNCTION MIOS_LCD_PrintBCD4
DESCRIPTION prints a 16-bit as BCD (decimal value) -- four digits
IN Low-byte in WREG, High-byte in MIOS_PARAMETER1
OUT four digits on LCD
USES BSR, MIOS_PARAMETER[123]
EXAMPLE
        ;; print four leftmost digits of TMP[12] on screen
        movff   TMP2, MIOS_PARAMETER1
        movf    TMP1, W
        call        MIOS_LCD_PrintBCD4
Back to the top

MIOS_LCD_PrintBCD5
FUNCTION MIOS_LCD_PrintBCD5
DESCRIPTION prints a 16-bit as BCD (decimal value) -- five digits
IN Low-byte in WREG, High-byte in MIOS_PARAMETER1
OUT five digits on LCD
USES BSR
EXAMPLE
        ;; print all five digits of TMP[12] on screen
        movff   TMP2, MIOS_PARAMETER1
        movf    TMP1, W
        call        MIOS_LCD_PrintBCD5
Back to the top

MIOS_LCD_PrintCString
FUNCTION MIOS_LCD_PrintCString
DESCRIPTION prints a 0-terminated string --- only provided by the MIOS C Wrapper!
IN not available in assembler
OUT some characters on LCD
USES BSR
Back to the top

MIOS_LCD_PrintChar
FUNCTION MIOS_LCD_PrintChar
DESCRIPTION prints a single ASCII character
IN character which should be print in WREG
OUT the character on LCD screen
USES BRS, TBLPTR
EXAMPLE
        ;; print four characters on screen
        movlw   'M'
        call    MIOS_LCD_PrintChar
        movlw   'I'
        call    MIOS_LCD_PrintChar
        movlw   'O'
        call    MIOS_LCD_PrintChar
        movlw   'S'
        call    MIOS_LCD_PrintChar
Back to the top

MIOS_LCD_PrintHex1
FUNCTION MIOS_LCD_PrintHex1
DESCRIPTION prints a 4-bit hex value
IN Value in WREG
OUT one digit on LCD
USES BSR
EXAMPLE
        ;; print leftmost nibble of TMP1 on screen
        movf    TMP1, W
        call        MIOS_LCD_PrintHex1
Back to the top

MIOS_LCD_PrintHex2
FUNCTION MIOS_LCD_PrintHex2
DESCRIPTION prints a 8-bit hex value
IN Value in WREG
OUT two digits on LCD
USES BSR
EXAMPLE
        ;; print content of TMP1 on screen
        movf    TMP1, W
        call        MIOS_LCD_PrintHex2
Back to the top

MIOS_LCD_PrintMessage
FUNCTION MIOS_LCD_PrintMessage
DESCRIPTION prints a message for about 2 seconds. Normal program flow will not be stopped during this time, just only the "DISPLAY_Tick" routine will not be called. After the message, "DISPLAY_Init" will be invoked before the next "DISPLAY_Tick"
IN Pointer to String in TBLPTR[LH]
First word of string must contain length and LCD position
OUT some characters on LCD for 2 seconds
USES BSR
EXAMPLE
        ;; defined somewhere *outside* the function!
  TEXT_POT_VALUE_0  STRING 11, 0x00, "Pot value: "

        ;; within the function: print string
        TABLE_ADDR TEXT_POT_VALUE_0
        call    MIOS_LCD_PrintMessage
        movlw   0x00
        call    MIOS_AIN_Pin7bitGet
        call    MIOS_LCD_PrintHex2
Back to the top

MIOS_LCD_PrintPreconfString
FUNCTION MIOS_LCD_PrintPreconfString
DESCRIPTION prints a preconfigured string
IN Pointer to String in TBLPTR[LH]
Stringlength in WREG
OUT some characters on LCD
USES BSR
EXAMPLE
        ;; defined somewhere *outside* the function!
  TEXT_WELCOME_0  db "Hello World!"

        ;; within the function: print string
        movlw   0x00 + 0
        call    MIOS_LCD_CursorSet
        TABLE_ADDR TEXT_WELCOME_0
        movlw   12
        call    MIOS_LCD_PrintPreconfString
Back to the top

MIOS_LCD_PrintString
FUNCTION MIOS_LCD_PrintString
DESCRIPTION prints a string
IN Pointer to String in TBLPTR[LH]
First word of string must contain length and LCD position
OUT some characters on LCD
USES BSR
EXAMPLE
        ;; defined somewhere *outside* the function!
  TEXT_WELCOME_0  STRING 12, 0x00, "Hello World!"

        ;; within the function: print string
        TABLE_ADDR TEXT_WELCOME_0
        call    MIOS_LCD_PrintString
Back to the top

MIOS_LCD_TypeAutoSet
FUNCTION MIOS_LCD_TypeAutoSet
DESCRIPTION derives the LCD type from the PIC ID header
IN -
OUT type in WREG,
additional LCD parameters in MIOS_PARAMETER1 and MIOS_PARAMETER2
USES BSR, TBLPTR
EXAMPLE

        ;; set LCD type to the specified type in the PIC ID header
        call        MIOS_LCD_TypeAutoSet

Back to the top

MIOS_LCD_TypeGet
FUNCTION MIOS_LCD_TypeGet
DESCRIPTION returns the LCD type Following LCDs are provided:
0x00: MIOS_LCD_TYPE_CLCD (character dotmatrix LCD)
0x01: MIOS_LCD_TYPE_GLCD0 (graphical LCD, KS0108 or HD61202 compatible)
0x06: MIOS_LCD_TYPE_MLCD (MIDI display, see SysEx implementation)
0x07: MIOS_LCD_TYPE_CUSTOM_LCD (custom LCD driver)
IN -
OUT LCD type in WREG and MIOS_PARAMETER1
USES -
EXAMPLE

        ;; branch depending on LCD type
        call        MIOS_LCD_TypeGet
        bnz     NoCLCD


        ;; !!! Better for branching depending on CLCD/GLCD type display !!!
        ;; !!! (works also with custom LCD driver                       !!!
        BRA_IFSET MIOS_BOX_CFG0, MIOS_BOX_CFG0_USE_GLCD, ACCESS, NoCLCD

Back to the top

MIOS_LCD_TypeSet
FUNCTION MIOS_LCD_TypeSet
DESCRIPTION sets the LCD type. Following LCDs are provided:
0x00: MIOS_LCD_TYPE_CLCD (character dotmatrix LCD)
0x01: MIOS_LCD_TYPE_GLCD0 (graphical LCD, KS0108 or HD61202 compatible)
0x06: MIOS_LCD_TYPE_MLCD (MIDI display, see SysEx implementation)
0x07: MIOS_LCD_TYPE_CUSTOM_LCD (custom LCD driver)
Note that the MIOS_LCD_TypeAutoSet function allows you to derive the LCD type from the PIC ID header! Use this function only if you want to force a special LCD type without changing the ID header of your PIC or if you want to set additional LCD options which are different from the default values
IN LCD type in WREG
LCD Option #1 in MIOS_PARAMETER1
LCD Option #2 in MIOS_PARAMETER2
OUT -
USES -
EXAMPLE

  The available LCD options differ with the used LCD type, here a list:

  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

  Type 0, CLCD:
     with MIOS_PARAMETER1 and MIOS_PARAMETER2 the enable (E) pins of
     the character displays are specified. By default the E input of
     the first CLCD should be connected to pin D.7, the E input of
     the second CLCD (if available) to C.4
     Following lines of code are necessary to achieve this:

        ;; use a CLCD, E input of first CLCD at D.7, E of second CLCD @C.4
        movlw        0x37                ; E1: D.7, 8bit interface
        movwf        MIOS_PARAMETER1
        movlw        0x24                ; E2: C.4, 8bit interface
        movwf        MIOS_PARAMETER2
        movlw        MIOS_LCD_TYPE_CLCD ; LCD type 0
        call        MIOS_LCD_TypeSet

     Note: the first digit of the parameter value sets the port number
             (A=0, B=1, C=2, D=3, E=4)
             the second digit sets the pin number (0-7)
             bit #7 sets the interface (0=8bit, 0=7bit)

     Example for CLCD with 4bit interface:
        ;; use a CLCD, E input of first CLCD at D.7, E of second CLCD @C.4
        ;; using the 4-bit interface:
        ;; -> connect MBHP_CORE:J15:D7-D4 of the core module to D7-D4 of the LCD
        ;; -> left MBHP_CORE:J15:D3-D0 of the core module open!
        ;; -> tie D3-D0 of the LCD to ground
        movlw        0x37 | 0x80        ; E1: D.7, 4bit interface
        movwf        MIOS_PARAMETER1
        movlw        0x24 | 0x80        ; E2: C.4, 4bit interface
        movwf        MIOS_PARAMETER2
        movlw        MIOS_LCD_TYPE_CLCD ; LCD type 0
        call        MIOS_LCD_TypeSet

     Tip: by changing these parameters dynamically you are also able to
            drive more than 2 LCDs with one core module. Only the number
            of free pins limit the number of CLCDs which can be driven!
            Don't forget to switch the appr. pins to output before using
            them, and call MIOS_LCD_Init for every display pair in your
            USER_Init

  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

 Type 1, KS0108 or HD61202 based
     with MIOS_PARAMETER1 it has to be specified if the chip select
     lines are inverted

        ;; use a KS0108 or HD61202 compatible graphical LCD with
        ;; non-inverted chip selects
        movlw        0x00
        movwf        MIOS_PARAMETER1
        movlw        MIOS_LCD_TYPE_GLCD0
        call        MIOS_LCD_TypeSet

   OR:
        ;; use a KS0108 or HD61202 compatible graphical LCD with inverted
        ;; chip selects
        movlw        0x01
        movwf        MIOS_PARAMETER1
        movlw        MIOS_LCD_TYPE_GLCD0
        call        MIOS_LCD_TypeSet

  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

 Type 2, T6963C based
     not supported anymore, use the custom driver instead which are
     available in the MIOS download section

  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

 Type 6, MIDI display
     see the MIOS SysEx implementation which is available in the MIOS
     download section
     MIOS_PARAMETER1 defines the device ID of the target core:

        ;; send MIDI messages to core with device ID 0x42
        clrf        MIOS_PARAMETER2                ; unused (yet)
        movlw        0x42
        movwf        MIOS_PARAMETER1                ; device ID of target core
        movlw        MIOS_LCD_TYPE_MLCD        ; LCD type #6
        call        MIOS_LCD_TypeSet

  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

 Type 7, custom LCD driver
     options are forwarded to the custom LCD driver
     following hooks have been prepared for an easy integration into
     MIOS:
          USER_LCD_Init
          USER_LCD_Clear
          USER_LCD_CursorSet
          USER_LCD_PrintChar

Back to the top

MIOS_LCD_YAddressGet
FUNCTION MIOS_LCD_YAddressGet
DESCRIPTION returns the Y offsets
IN -
OUT Line Y0 address in MIOS_PARAMETER1,
Line Y1 address in MIOS_PARAMETER2,
Line Y2 address in MIOS_PARAMETER3,
Line Y3 address in WREG
USES -
Back to the top

MIOS_LCD_YAddressSet
FUNCTION MIOS_LCD_YAddressSet
DESCRIPTION maps the Y position of the cursor to the appr. cursor address of character and graphical displays.
By default the positions are configured for 2x16, 2x20, 4x20 and 2x40 displays:
Line0 -> MIOS cursor offset: 0x00 -> cursor address 0x00
Line1 -> MIOS cursor offset: 0x40 -> cursor address 0x40
Line2 -> MIOS cursor offset: 0x80 -> cursor address 0x14 (4x20 only)
Line3 -> MIOS cursor offset: 0xc0 -> cursor address 0x54 (4x20 only)
For 4x16 displays, the configuration has to be changed:
Line0 -> MIOS cursor offset: 0x00 -> cursor address 0x00
Line1 -> MIOS cursor offset: 0x40 -> cursor address 0x40
Line2 -> MIOS cursor offset: 0x80 -> cursor address 0x10 (4x16 only)
Line3 -> MIOS cursor offset: 0xc0 -> cursor address 0x50 (4x16 only)
For 2 character displays connected to one core use: Line0 -> MIOS cursor offset: 0x00 -> cursor address 0x00
Line1 -> MIOS cursor offset: 0x40 -> cursor address 0x40
Line2 -> MIOS cursor offset: 0x80 -> cursor address 0x80
Line3 -> MIOS cursor offset: 0xc0 -> cursor address 0xc0
(first LCD is addressed by 0x00-0x7f, second LCD is addressed by 0x80-0xff)

This function allows also to center the screen if you want to run
Applications which have been developed for a 2x16 display on a
larger display. Example for a 2x20 Display:
Line0 -> MIOS cursor offset: 0x00 -> cursor address 0x04
Line1 -> MIOS cursor offset: 0x40 -> cursor address 0x44
Line2 -> don't care
Line3 -> don't care
IN Line Y0 address in MIOS_PARAMETER1,
Line Y1 address in MIOS_PARAMETER2,
Line Y2 address in MIOS_PARAMETER3,
Line Y3 address in WREG
OUT -
USES -
EXAMPLE

        ;; configure the offsets for a 4x16 LCD:
        movlw        0x00
        movwf        MIOS_PARAMETER1
        movlw        0x40
        movwf        MIOS_PARAMETER2
        movlw        0x10
        movwf        MIOS_PARAMETER3
        movlw        0x50
        call        MIOS_LCD_YAddressSet

        ;; configure MIOS for 2 character LCDs:
        ;; (see also http://www.ucapps.de/mbhp_lcd.html )
        movlw        0x00
        movwf        MIOS_PARAMETER1
        movlw        0x40
        movwf        MIOS_PARAMETER2
        movlw        0x80
        movwf        MIOS_PARAMETER3
        movlw        0xc0
        call        MIOS_LCD_YAddressSet

Back to the top

MIOS_CLCD_SpecialCharInit
FUNCTION MIOS_CLCD_SpecialCharInit
DESCRIPTION initializes one of 8 special characters provided by a HD44780 compatible character LCD
IN number of special character (0-7) in WREG
pointer to special char pattern in TBLPTR (must consist of 8
entries for every character-line)
OUT TBLPTR will be set to next table entry (TBLPTR+=8)
USES BRS, TBLPTR
EXAMPLE
        ;; use a left-arrow as special char #2
        TABLE_ADDR SPECIAL_CHAR_LEFT_ARROW
        movlw   0x02
        call        MIOS_CLCD_SpecialCharInit
        ;; set cursor to 0
        movlw        0x00
        call        MIOS_LCD_CursorSet
        ;; print the special char
        movlw        0x02
        call        MIOS_LCD_PrintChar
        return

 SPECIAL_CHAR_LEFT_ARROW
        ;; due to an imperfection in the MPASM we have
        ;; to write two bytes in every line :-(
        db b'00000011', b'00000111' ; 1st and 2nd line of special char
        db b'00001111', b'00011111' ; 3rd and 4th line of special char
        db b'00011111', b'00001111' ; 5th and 6th line of special char
        db b'00000111', b'00000011' ; 7th and 8th line of special char

Back to the top

MIOS_CLCD_SpecialCharsInit
FUNCTION MIOS_CLCD_SpecialCharsInit
DESCRIPTION initializes all 8 special characters provided by a HD44780 compatible character LCD
See also: MIOS_CLCD_SpecialCharInit
IN pointer to special char patterns in TBLPTR (must consist of 8*8
entries for every character and line)
OUT TBLPTR will be set to next table entry (TBLPTR+=64)
USES BRS, TBLPTR
EXAMPLE
     for a single character: see MIOS_CLCD_SpecialCharInit
     this function does the same, but it initializes
     all 8 characters at once

Back to the top

MIOS_GLCD_FontInit
FUNCTION MIOS_GLCD_FontInit
DESCRIPTION initializes a font, (animated icon) or bitmap Note that this function works with graphical LCDs only!
IN pointer to font header in TBLPTR
OUT -
USES BRS, TBLPTR
EXAMPLE
        ;; set default font:
        TABLE_ADDR MIOS_GLCD_FONT
        call        MIOS_GLCD_FontInit
        ;; set cursor to 0
        movlw        0x00
        call        MIOS_LCD_CursorSet
        ;; print character 'A'
        movlw        'A'
        call        MIOS_LCD_PrintChar
Back to the top

MIOS_GLCD_GCursorGet
FUNCTION MIOS_GLCD_GCursorGet
DESCRIPTION returns the position of the graphical cursor
Note that this function works with graphical LCDs only!
IN -
OUT X position in WREG (0-239)
Y position in MIOS_PARAMETER1 (0-7)
USES BRS, TBLPTR
Back to the top

MIOS_GLCD_GCursorSet
FUNCTION MIOS_GLCD_GCursorSet
DESCRIPTION sets the graphical cursor on a LCD screen
Note that this function works with graphical LCDs only!
IN X position in WREG (0-239)
Y position in MIOS_PARAMETER1 (0-7)
OUT -
USES BRS, TBLPTR
EXAMPLE
        ;; set graphical cursor to 160/7:
        movlw        7
        movwf        MIOS_PARAMETER1
        movlw        160
        call        MIOS_GLCD_GCursorSet
Back to the top

MIOS_EEPROM_Read
FUNCTION MIOS_EEPROM_Read
DESCRIPTION reads a byte from EEPROM.
IN address in EEADR (0x00-0xff) and EEADRH (0-3, PIC18F4620 only)
OUT EEPROM content in WREG
EEADR will be incremented
EEADRH (PIC18F4620) will *not* be incremented on EEADR overrun!
USES BSR, EEADR, EEDATA, EECON1, EECON2
EXAMPLE

        ;; load a byte from address 0x80
        movlw        0x80                        ; write 0x80 to address register
        movwf        EEADR
        call        MIOS_EEPROM_Read        ; read from EEPROM

Back to the top

MIOS_EEPROM_ReadPage
FUNCTION MIOS_EEPROM_ReadPage
DESCRIPTION reads a 64 bytes page from EEPROM
The internal EEPROM of PIC18F452 doesn't provide a page read by itself, therefore this function calls MIOS_EEPROM_Read 64 times.
IN pointer to read buffer (64 bytes) in FSR1
address in EEADR (0x00-0xc0) and EEADRH (0-3, PIC18F4620 only)
OUT EEPROM content in read buffer
EEADR will be incremented to next page address (+64)
EEADRH (PIC18F4620) will *not* be incremented on EEADR overrun!
FSR1 will be left untouched
USES BSR, EEADR, EEDATA, EECON1, EECON2
EXAMPLE

        ;; read a page of 64 bytes from EEPROM at address 0x40
        movlw        0x40                        ; set start address of page
        movwf   EEADR                   ; (must be aligned to 64)
        lfsr        FSR1, 0x100                ; a free 64 byte buffer in RAM which
                                        : contains some data
        call        MIOS_EEPROM_ReadPage        ; start the page read

Back to the top

MIOS_EEPROM_Write
FUNCTION MIOS_EEPROM_Write
DESCRIPTION writes a byte into EEPROM.
Write access will be skipped if content is equal to the byte which should be written
Returned Error Status:
0x00: no error
0x01: byte mismatch (write failed)
IN byte in WREG, address in EEADR (0x00-0xff) and EEADRH (0-3, PIC18F4620 only)
OUT error status in WREG and MIOS_PARAMETER1
EEADR will be incremented
EEADRH (PIC18F4620) will *not* be incremented on EEADR overrun!
USES BSR, EEADR, EEDATA, EECON1, EECON2
EXAMPLE

        ;; write 0x47 0x11 into EEPROM at address 0x80/0x81
        movlw        0x80                        ; write 0x80 to address register
        movwf        EEADR
        movlw        0x47                        ; write 0x47 to 0x80
        call        MIOS_EEPROM_Write        ; (EEADR will be incremented)
        bnz        EEPROMProgrammingFailed        ; branch to your exception handler
                                        ; if necessary
        movlw        0x11                        ; write 0x11 to 0x81
        call        MIOS_EEPROM_Write        ; (EEADR will be incremented)
        bnz        EEPROMProgrammingFailed        ; branch to your exception handler
                                        ; if necessary

Back to the top

MIOS_EEPROM_WritePage
FUNCTION MIOS_EEPROM_WritePage
DESCRIPTION writes a 64 bytes page into EEPROM.
The internal EEPROM of PIC18F452 doesn't provide a page write by itself, therefore this function calls MIOS_EEPROM_Write 64 times.
Returned Error Status:
0x00: no error
0x01: byte mismatch (one or more writes failed)
IN pointer to write buffer (64 bytes) in FSR1
address in EEADR (0x00-0xc0) and EEADRH (0-3, PIC18F4620 only)
OUT error status in WREG and MIOS_PARAMETER1
EEADR will be incremented to the next page address (+64)
EEADRH (PIC18F4620) will *not* be incremented on EEADR overrun!
FSR1 will be left untouched
USES BSR, EEADR, EEDATA, EECON1, EECON2
EXAMPLE

        ;; write a page of 64 bytes to EEPROM memory at address 0x80
        movlw        0x80                        ; set start address of page
        movwf   EEADR                   ; (must be aligned to 64)
        lfsr        FSR1, 0x100                ; a free 64 byte buffer in RAM which
                                        : contains some data
        call        MIOS_EEPROM_WritePage        ; initiate the write
        bnz        EEPROMProgrammingFailed        ; branch to your exception handler
                                        ; if necessary

Back to the top

MIOS_FLASH_Read
FUNCTION MIOS_FLASH_Read
DESCRIPTION copies 64 bytes from FLASH memory to buffer
IN pointer to read buffer (64 bytes) in FSR1
flash address in TBLPRT_[LH] (0x0000-0x7fc0, must be aligned to 64 byte page)
OUT memory dump in read buffer
TBLPTR will be incremented to next page address
FSR1 will be left untouched
USES BSR, TBLPTR[LH], TABLAT
EXAMPLE

        ;; read a page of 64 bytes from flash memory at address 0x7000
        TABLE_ADDR 0x7000                ; load address into TABLPTR[LH]
        lfsr        FSR1, 0x100                ; a free 64 byte buffer in RAM
        call        MIOS_FLASH_Read                ; initiate the read
        ;; flash dump now in buffer from 0x100-0x13f

Back to the top

MIOS_FLASH_Write
FUNCTION MIOS_FLASH_Write
DESCRIPTION writes 64 bytes into FLASH memory
Write access will be skipped if content is equal to the bytes in the buffer. Writes to MIOS prgram space will be prevented:
PIC18F452: 0x0000-0x2fff not writable PIC18F4620: 0x0000-0x2fff not writable Returned Error Status:
0x00: no error
0x01: byte mismatch (write failed)
0x02: access error (memory protected)
IN pointer to write buffer (64 bytes) in FSR1
flash address in TBLPRT_[LH] (must be aligned to 64 byte page)
OUT error status in WREG and MIOS_PARAMETER1
TBLPTR will be incremented to next page address (+64)
FSR1 will be left untouched
USES BSR, TBLPTR[LH], TABLAT, EECON1, EECON2
EXAMPLE

        ;; write a page of 64 bytes to flash memory at address 0x7000
        TABLE_ADDR 0x7000                ; load address into TABLPTR[LH]
        lfsr        FSR1, 0x100                ; a free 64 byte buffer in RAM which
                                        ; contains some data
        call        MIOS_FLASH_Write        ; initiate the write
        bnz        FlashProgrammingFailed        ; branch to your exception handler
                                        ; if necessary

Back to the top

MIOS_BANKSTICK_CtrlGet
FUNCTION MIOS_BANKSTICK_CtrlGet
DESCRIPTION returns the BankStick control status
IN -
OUT WREG[2..0]: A2-A0
WREG[7]: Verify disabled
USES -
Back to the top

MIOS_BANKSTICK_CtrlSet
FUNCTION MIOS_BANKSTICK_CtrlSet
DESCRIPTION sets the BankStick control register
bit 2-0: selects the BankStick (1 of 8, address defined with pin A0-A2 of the EEPROM)
bit 7: if set, the verify during BankStick write will be disabled
IN control register content in WREG
OUT -
USES -
EXAMPLE
        ;; write 0x47 0x11 to address 0x3000-0x3001 of the BankStick number 7
        movlw        0x07                        ; select 8th BankStick
        call        MIOS_BANKSTICK_CtrlSet
        movlw        0x00                        ; store low-byte of address in
        movwf        MIOS_PARAMETER1                ; MIOS_PARAMETER1
        movlw        0x30                        ; store high-byte of address in
        movwf        MIOS_PARAMETER2                ; MIOS_PARAMETER2
        movlw        0x47                        ; write 0x47 to 0x3000
        call        MIOS_BANKSTICK_Write        ; (address will be incremented
                                        ; after write)
        bnz        BSProgrammingFailed        ; branch to your exception handler
                                        ; if necessary
        movlw        0x11                        ; write 0x11 to 0x3001
        call        MIOS_BANKSTICK_Write        ; (address will be incremented
                                        ; after write)
        bnz        BSProgrammingFailed        ; branch to your exception handler
                                        ; if necessary
        movlw        0x00                        ; select first BankStick again
        call        MIOS_BANKSTICK_CtrlSet
Back to the top

MIOS_BANKSTICK_Read
FUNCTION MIOS_BANKSTICK_Read
DESCRIPTION reads a byte from BankStick.
IN address in MIOS_PARAMETER[12] (0x0000-0xffff)
OUT BankStick content in WREG
MIOS_PARAMETER[12] will be incremented
MIOS_BOX_STAT[MIOS_BOX_STAT_BS_AVAILABLE] is zero if read failed
USES BSR, MIOS_PARAMETER[12]
EXAMPLE

        ;; load a byte from address 0x7fff (the last in a 32k BankStick)
        movlw        0xff                        ; initialize pointer to BankStick
                                        ; address
        movwf        MIOS_PARAMETER1                ; -> 0x7fff
        movlw        0x7f
        movwf        MIOS_PARAMETER2
        call        MIOS_BANKSTICK_Read        ; load byte from BankStick
                                        ; branch to error exception
                                        ; routine if neccesary
        BRA_IFCLR MIOS_BOX_STAT, MIOS_BOX_STAT_BS_AVAILABLE, ACCESS, BankStickNotAvl

Back to the top

MIOS_BANKSTICK_ReadPage
FUNCTION MIOS_BANKSTICK_ReadPage
DESCRIPTION reads a 64 bytes page from BankStick.
IN pointer to read buffer (64 bytes) in FSR1
address in MIOS_PARAMETER[12] (0x0000-0xffc0)
OUT BankStick content in read buffer
MIOS_PARAMETER[12] will be incremented to next page address (+64)
FSR1 will be left untouched
MIOS_BOX_STAT[MIOS_BOX_STAT_BS_AVAILABLE] is also zero if write failed
USES BSR, MIOS_PARAMETER[12]
EXAMPLE

        ;; read a page of 64 bytes from BankStick memory at address 0x1240
        movlw        0x40                        ; store low-byte of address in
        movwf        MIOS_PARAMETER1                ; MIOS_PARAMETER1
        movlw        0x12                        ; store high-byte of address in
        movwf        MIOS_PARAMETER2                ; MIOS_PARAMETER2
        lfsr        FSR1, 0x100                ; a free 64 byte buffer in RAM which
                                        : contains some data
        call        MIOS_BANKSTICK_ReadPage        ; start the page read
        BRA_IFCLR MIOS_BOX_STAT, MIOS_BOX_STAT_BS_AVAILABLE, ACCESS, BankStickNotAvl

Back to the top

MIOS_BANKSTICK_Write
FUNCTION MIOS_BANKSTICK_Write
DESCRIPTION writes a byte into BankStick.
If verify mode has been enabled with MIOS_BANKSTICK_CtrlSet, write access will be skipped if content is equal to the byte which should be written
Returned Error Status:
0x00: no error
0x01: byte mismatch (write failed) -- only set if verify enabled
0x02: BankStick not available
IN byte in WREG, address in MIOS_PARAMETER[12] (0x0000-0xffff)
OUT error status in WREG
MIOS_PARAMETER[12] will be incremented
MIOS_BOX_STAT[MIOS_BOX_STAT_BS_AVAILABLE] cleared if write failed
USES BSR, MIOS_PARAMETER[12]
EXAMPLE

        ;; write 0x47 0x11 to address 0x3000-0x3001 of the BankStick
        movlw        0x00                        ; store low-byte of address in
        movwf        MIOS_PARAMETER1                ; MIOS_PARAMETER1
        movlw        0x30                        ; store high-byte of address in
        movwf        MIOS_PARAMETER2                ; MIOS_PARAMETER2
        movlw        0x47                        ; write 0x47 to 0x3000
        call        MIOS_BANKSTICK_Write        ; (address will be incremented
                                        ; after write)
        bnz        BSProgrammingFailed        ; branch to your exception handler
                                        ; if necessary
        movlw        0x11                        ; write 0x11 to 0x3001
        call        MIOS_BANKSTICK_Write        ; (address will be incremented
                                        ;  after write)
        bnz        BSProgrammingFailed        ; branch to your exception handler
                                        ; if necessary

Back to the top

MIOS_BANKSTICK_WritePage
FUNCTION MIOS_BANKSTICK_WritePage
DESCRIPTION writes a 64 bytes page into BankStick. If verify mode has been enabled with MIOS_BANKSTICK_CtrlSet, write access will be skipped if content is equal to the byte which should be written Returned Error Status: 0x00: no error 0x01: byte mismatch (write failed) -- only set if verify enabled 0x02: BankStick not available
IN pointer to write buffer (64 bytes) in FSR1
address in MIOS_PARAMETER[12] (0x0000-0xffc0)
OUT error status in WREG
MIOS_PARAMETER[12] will be incremented to next page address (+64)
FSR1 will be left untouched
MIOS_BOX_STAT[MIOS_BOX_STAT_BS_AVAILABLE] is cleared if write failed
USES BSR, MIOS_PARAMETER[12]
EXAMPLE

        ;; write a page of 64 bytes to BankStick memory at address 0x1240
        movlw        0x40                        ; store low-byte of address in
        movwf        MIOS_PARAMETER1                ; MIOS_PARAMETER1
        movlw        0x12                        ; store high-byte of address in
        movwf        MIOS_PARAMETER2                ; MIOS_PARAMETER2
        lfsr        FSR1, 0x100                ; a free 64 byte buffer in RAM which
                                        : contains some data
        call        MIOS_BANKSTICK_WritePage; initiate the write
        bnz        BSProgrammingFailed        ; branch to your exception handler
                                        ; if necessary

Back to the top

MIOS_IIC_AckSend
FUNCTION MIOS_IIC_AckSend
DESCRIPTION sends a ACK (acknowledge) to the slave(s)
IN -
OUT -
USES -
EXAMPLE
        see MIOS_IIC_ByteSend and MIOS_IIC_ByteReceive
Back to the top

MIOS_IIC_ByteReceive
FUNCTION MIOS_IIC_ByteReceive
DESCRIPTION receives a byte from a IIC slave.
IN -
OUT received byte in WREG
USES BSR
EXAMPLE

        ;; receive three bytes from the IIC slave with ID 0x12

        rcall        MIOS_IIC_Start                ; start IIC
        movlw        0x12 | 1                ; send device address -
        call        MIOS_IIC_ByteSend        ;    set bit #0 to notify a read!!!
        ;; don't continue if IIC device not available
        BRA_IFCLR MIOS_BOX_STAT, MIOS_BOX_STAT_BS_AVAILABLE, ACCESS, ReadFailed

        call        MIOS_IIC_ByteReceive        ; read first byte
        movwf   TMP1                        ; save it in TMP1
        call        MIOS_IIC_AckSend        ; send acknowledge
        call        MIOS_IIC_ByteReceive        ; read second byte
        movwf   TMP2                        ; save it in TMP2
        call        MIOS_IIC_AckSend        ; send acknowledge
        call        MIOS_IIC_ByteReceive        ; read third byte
        movwf   TMP3                        ; save it in TMP3
  ReadFailed:
        call        MIOS_IIC_NakSend        ; send disacknowledge!!!
        call        MIOS_IIC_Stop                ; stop IIC

  For more details about the IIC protocol (officially called I2C), see
     http://www.semiconductors.philips.com/buses/i2c/
Back to the top

MIOS_IIC_ByteSend
FUNCTION MIOS_IIC_ByteSend
DESCRIPTION sends a byte over the IIC bus and checks for acknowledge.
If the slave didn't send an acknowledge, the (MIOS_BOX_STAT_)BS_AVAILABLE flag in MIOS_BOX_STAT will be cleared.
IN byte which should be sent in WREG
OUT WREG==0x00 if NAK has been received, otherwise != 0x00
due to compatibility reasons, MIOS_BOX_STAT.MIOS_BOX_STAT_BS_AVAILABLE set so long ACK is received
USES BSR
EXAMPLE

        ;; send 0x34, 0x56, 0x78 to the IIC slave with ID 0x12

        call        MIOS_IIC_Start                ; start IIC
        movlw        0x12                        ; send device address
        call        MIOS_IIC_ByteSend        ; bit #0 cleared to notify a write!!!
        movlw        0x34                        ; send first data byte
        call        MIOS_IIC_ByteSend
        movlw        0x56                        ; send second data byte
        call        MIOS_IIC_ByteSend
        movlw        0x78                        ; send third data byte
        call        MIOS_IIC_ByteSend
        call        MIOS_IIC_Stop                ; stop IIC

  For more details about the IIC protocol (officially called I2C), see
     http://www.semiconductors.philips.com/buses/i2c/

  An enhanced example with retry can be
  found at the MBHP_IIC_MIDI page
Back to the top

MIOS_IIC_CtrlGet
FUNCTION MIOS_IIC_CtrlGet
DESCRIPTION returns the IIC control status
IN -
OUT WREG[0]: clock stretching enabled
USES -
Back to the top

MIOS_IIC_CtrlSet
FUNCTION MIOS_IIC_CtrlSet
DESCRIPTION enables the "clock stretching" like specified in the IIC specification http://www.semiconductors.philips.com/buses/i2c/ which is required for some IIC slaves which cannot service the bus immediately on a request.
IN WREG = 0x00: clock stretching disabled
WREG = 0x01: clock stretching enabled
OUT -
USES -
NOTE if enabled, you have to add a 1k pull-up resistor to the SCL line (Pin #22 of the PIC)
EXAMPLE
        ;; enable clock stretching
        movlw   0x01
        call    MIOS_IIC_CtrlSet
Back to the top

MIOS_IIC_NakSend
FUNCTION MIOS_IIC_NakSend
DESCRIPTION sends a NAK (not acknowledge) to the slave(s)
IN -
OUT -
USES -
EXAMPLE
        see MIOS_IIC_ByteSend and MIOS_IIC_ByteReceive
Back to the top

MIOS_IIC_Start
FUNCTION MIOS_IIC_Start
DESCRIPTION sends the IIC start condition (SCL=1, SDA 1->0)
IN -
OUT -
USES -
EXAMPLE
        see MIOS_IIC_ByteSend and MIOS_IIC_ByteReceive
Back to the top

MIOS_IIC_Stop
FUNCTION MIOS_IIC_Stop
DESCRIPTION sends the IIC stop condition (SCL=0->1, SDA 0->1)
IN -
OUT -
USES -
EXAMPLE
        see MIOS_IIC_ByteSend and MIOS_IIC_ByteReceive
Back to the top

MIOS_TIMER_Init
FUNCTION MIOS_TIMER_Init
DESCRIPTION initializes the timer which calls USER_Timer periodically and starts it. The resolution of the timer is 100nS with Prescaler 1:1, 200nS with 1:2, 400nS with 1:4, 800nS with 1:8. The period (number of clocks) is specified as 16 bit value.
IN prescaler value in WREG:
0x00: 1:1
0x01: 1:2
0x02: 1:4
0x03: 1:8
number of ticks (low-byte) in MIOS_PARAMETER1
number of ticks (high-byte) in MIOS_PARAMETER2
OUT -
USES BSR
EXAMPLE
        ;; we want to setup the timer with a frequency of 500 Hz = 2 mS
        ;; prescaler 1:1 should be used
        ;; calculate the required number of clocks for this period:
        ;; clocks = period / 100 nS = 2 mS / 100 nS = 20000
        ;; calculate low and high byte:
        ;;    low byte  = period & 0xff
        ;;    high byte = period >> 8
        ;; therefore:
        movlw        20000 & 0xff
        movwf        MIOS_PARAMETER1
        movlw        20000 >> 8
        movwf        MIOS_PARAMETER2
        movlw        0x00
        call        MIOS_TIMER_Init

        ;; now the USER_Timer function is called every 2 mS!
Back to the top

MIOS_TIMER_ReInit
FUNCTION MIOS_TIMER_ReInit
DESCRIPTION same like MIOS_TIMER_Init, but the timer won't be reset to allow a smooth re-initialization
IN prescaler value in WREG:
0x00: 1:1
0x01: 1:2
0x02: 1:4
0x03: 1:8
number of ticks (low-byte) in MIOS_PARAMETER1
number of ticks (high-byte) in MIOS_PARAMETER2
OUT -
USES BSR
Back to the top

MIOS_TIMER_Start
FUNCTION MIOS_TIMER_Start
DESCRIPTION (re)starts the timer if it has been stopped before
IN -
OUT -
USES -
Back to the top

MIOS_TIMER_Stop
FUNCTION MIOS_TIMER_Stop
DESCRIPTION stops the timer
IN -
OUT -
USES -
Back to the top

MIOS_HLP_16bitAddSaturate
FUNCTION MIOS_HLP_16bitAddSaturate
DESCRIPTION adds a signed 8-bit value to a 16 bit value and saturates
That means: if the resulting value is greater than the given max value, the result will be saturated to the max value. If the resulting value is less than 0, the result will be saturated to 0
Important: the 16-bit value must be aligned to an even word address (0x10, 0x12, 0x14, ...). First address contains the low-byte and the second address contains the high-byte
IN 8-bit signed value in WREG
pointer to low/high byte which should be modified in FSR1
low-byte of max value in MIOS_PARAMETER1
high-byte of max value in MIOS_PARAMETER2
OUT returns new absolute value in FSR1
WREG and MIOS_PARAMETER1[0] is 1, if the value has been changed, 0 if it
is equal to the old value
USES BSR, INDF1 (FSR1 untouched), MIOS_PARAMETER[123]
EXAMPLE

        ;; subtract -5 from the 16-bit value
        ;; [FSR1] == INDF1 is 0x0002
        ;; max-value is 0x0fff
        movlw   0xff                        ; low-byte of max value
        movwf   MIOS_PARAMETER1
        movlw   0x0f                        ; high-byte of max value
        movwf   MIOS_PARAMETER2
        movlw        -5                        ; incrementer is -5
        call        MIOS_HLP_16bitAddSaturate
        ;; now INDF1 contains 0x0000 due to saturation
        ;; MIOS_PARAMETER1[0] is 1 since the value has been changed

        ;; subtract -5 again
        ;; [FSR1] == INDF1 is 0x0000
        movlw   0xff                        ; low-byte of max value
        movwf   MIOS_PARAMETER1
        movlw   0x0f                        ; high-byte of max value
        movwf   MIOS_PARAMETER2
        movlw        -5                        ; incrementer is -5
        call        MIOS_HLP_16bitAddSaturate
        ;; now INDF1 contains 0x0000 due to saturation
        ;; MIOS_PARAMETER1[0] is 0 since the value has NOT been changed



        ;; add 30 to the 16-bit value
        ;; [FSR1] == INDF1 is 0x0ffe
        ;; max-value is 0x0fff
        movlw   0xff                        ; low-byte of max value
        movwf   MIOS_PARAMETER1
        movlw   0x0f                        ; high-byte of max value
        movwf   MIOS_PARAMETER2
        movlw        30                        ; incrementer is 30
        call        MIOS_HLP_16bitAddSaturate
        ;; now INDF1 contains 0x0fff due to saturation
        ;; MIOS_PARAMETER1[0] is 1 since the value has been changed

Back to the top

MIOS_HLP_AddressFromTable
FUNCTION MIOS_HLP_AddressFromTable
DESCRIPTION this help function reads a pointer from a table and moves it to TBLPTR. On this way linked lists can be realized
IN pointer to entry in TBLPTR[LH]
OUT new pointer in TBLPTR[LH]
USES -
NOTE TBLPTRU not read or changed. Table should be located within a 64k segment!
Back to the top

MIOS_HLP_Dec2BCD
FUNCTION MIOS_HLP_Dec2BCD
DESCRIPTION converts a 16-bit decimal value to BCD
IN low-byte in WREG
high-byte in MIOS_PARAMETER1
OUT rightmost digits (n1*10^1 and n0*10^0) in WREG and MIOS_PARAMETER1
middle digits (n3*10^3 and n2*10^2) in MIOS_PARAMETER2
leftmost digit (n5*10^4) in MIOS_PARAMETER3
USES BSR, MIOS_PARAMETER[123]
EXAMPLE

        ;; get the BCD code from 12345
        movlw        (12345) >> 8                ; store high-byte in MIOS_PARAMETER1
        movwf        MIOS_PARAMETER1
        movlw        (12345) & 0xff                ; store low-byte in WREG
        call        MIOS_HLP_Dec2BCD        ; convert to BCD code
        ;; now:
        ;;    MIOS_PARAMETER3 contains the hex-value 0x01
        ;;    MIOS_PARAMETER2 contains the hex-value 0x23
        ;;    MIOS_PARAMETER1 contains the hex-value 0x45
        ;;    WREG            contains also the hex-value 0x45
Back to the top

MIOS_HLP_GetBitANDMask
FUNCTION MIOS_HLP_GetBitANDMask
DESCRIPTION this help function is usefull for bit manipulations
IN see map below
OUT 0x00 -> b'11111110'
0x01 -> b'11111101'
0x02 -> b'11111011'
0x03 -> b'11110111'
0x04 -> b'11101111'
0x05 -> b'11011111'
0x06 -> b'10111111'
0x07 -> b'01111111'
USES -
Back to the top

MIOS_HLP_GetBitORMask
FUNCTION MIOS_HLP_GetBitORMask
DESCRIPTION this help function is usefull for bit manipulations
IN see map below
OUT 0x00 -> b'00000001'
0x01 -> b'00000010'
0x02 -> b'00000100'
0x03 -> b'00001000'
0x04 -> b'00010000'
0x05 -> b'00100000'
0x06 -> b'01000000'
0x07 -> b'10000000'
USES -
Back to the top

MIOS_HLP_GetIndex_2bytes
FUNCTION MIOS_HLP_GetIndex_2bytes
DESCRIPTION this help function can be used for jumptables which contain 2-byte instructions (-> rgoto). Note that the JUMPTABLE_2BYTES macro allows to use this function securely without the danger that the code behind the table will be executed if the index number in WREG is greater than the number of entries
IN index in WREG
OUT jump to indexed entry
USES -
EXAMPLE
        ;; index is already in WREG
        JUMPTABLE_2BYTES 4        ; (4 entries)
        rgoto        Function_for_WREG_00
        rgoto        Function_for_WREG_01
        rgoto        Function_for_WREG_02
        rgoto        Function_for_WREG_03

Function_for_WREG_00
        ;; ...
Function_for_WREG_01
        ;; ...
Function_for_WREG_02
        ;; ...
Function_for_WREG_03
        ;; ...

Back to the top

MIOS_HLP_GetIndex_4bytes
FUNCTION MIOS_HLP_GetIndex_4bytes
DESCRIPTION this help function can be used for jumptables which contain 4-byte instructions (-> goto). Note that the JUMPTABLE_4BYTES macro allows to use this function securely without the danger that the code behind the table will be executed if the index number in WREG is greater than the number of entries
IN index in WREG
OUT jump to indexed entry
USES -
EXAMPLE
        ;; index is already in WREG
        JUMPTABLE_4BYTES 4        ; (4 entries)
        goto        Function_for_WREG_00
        goto        Function_for_WREG_01
        goto        Function_for_WREG_02
        goto        Function_for_WREG_03

        ;; far away from this jumptable (so that rgoto cannot be used...)

Function_for_WREG_00
        ;; ...
Function_for_WREG_01
        ;; ...
Function_for_WREG_02
        ;; ...
Function_for_WREG_03
        ;; ...

Back to the top

MIOS_HLP_IndirectJump
FUNCTION MIOS_HLP_IndirectJump
DESCRIPTION this help function reads a pointer from a table and jumps to this pointer
IN pointer to entry in TBLPTR[LH]
OUT jumps indirectly to [TBLPTR[LH]]
USES WREG
NOTE TBLPTRU not read or changed. Table and target address should be located within a 64k segment!
Back to the top

MIOS_Delay
FUNCTION MIOS_Delay
DESCRIPTION waits for an exact time
note that this function will not work within an interrupt service routine!
IN time in ms (0-255)
OUT -
USES BSR
EXAMPLE

        ;; wait for exact 250 ms
        movlw        250
        call        MIOS_Delay

Back to the top

MIOS_GPCounterGet
FUNCTION MIOS_GPCounterGet
DESCRIPTION get value of general purpose counter, which is incremented every millisecond
IN -
OUT value of general purpose counter in WREG and MIOS_PARAMETER1
USES BSR
Back to the top

MIOS_Reset
FUNCTION MIOS_Reset
DESCRIPTION waits until the Tx MIDI buffer is empty, thereafter resets the OS
IN -
OUT -
USES -
Back to the top

MIOS_SystemResume
FUNCTION MIOS_SystemResume
DESCRIPTION resumes all system tasks
IN -
OUT -
USES -
Back to the top

MIOS_SystemSuspend
FUNCTION MIOS_SystemSuspend
DESCRIPTION suspends all system and user tasks except for the IO MIDI handler
IN -
OUT -
USES FSR1
Back to the top

MIOS_UserResume
FUNCTION MIOS_UserResume
DESCRIPTION resumes all user tasks
IN -
OUT -
USES -
Back to the top

MIOS_UserSuspend
FUNCTION MIOS_UserSuspend
DESCRIPTION suspends all user tasks
IN -
OUT -
USES -
Back to the top

USER_AIN_NotifyChange
FUNCTION USER_AIN_NotifyChange
DESCRIPTION This function is called by MIOS when a pot has been moved
IN Pot number in WREG and MIOS_PARAMETER1
LSB value in MIOS_PARAMETER2
MSB value in MIOS_PARAMETER3
OUT -
ISR no
Back to the top

USER_DIN_NotifyToggle
FUNCTION USER_DIN_NotifyToggle
DESCRIPTION This function is called by MIOS when an button has been toggled
IN Button number in WREG and MIOS_PARAMETER1
Button value MIOS_PARAMETER2:
- 1 if button has been released (=5V)
- 0 if button has been pressed (=0V)
OUT -
ISR no
Back to the top

USER_DISPLAY_Init
FUNCTION USER_DISPLAY_Init
DESCRIPTION This function is called by MIOS when the display content should be initialized. Thats the case during startup and after a temporary message has been printed on the screen
IN -
OUT -
ISR no
Back to the top

USER_DISPLAY_Tick
FUNCTION USER_DISPLAY_Tick
DESCRIPTION This function is called by MIOS in the mainloop when no temporary message is shown on the screen.
IN -
OUT -
ISR no
Back to the top

USER_ENC_NotifyChange
FUNCTION USER_ENC_NotifyChange
DESCRIPTION This function is called by MIOS when an encoder has been moved
IN Encoder number in WREG and MIOS_PARAMETER1
signed incrementer value in MIOS_PARAMETER2:
- is positive when encoder has been turned clockwise
- is negative when encoder has been turned counter clockwise
OUT -
ISR no
Back to the top

USER_Init
FUNCTION USER_Init
DESCRIPTION This function is called by MIOS after startup to initialize the application
IN -
OUT -
ISR no
Back to the top

USER_LCD_Clear
FUNCTION USER_LCD_Clear
DESCRIPTION This function is called by MIOS when the custom LCD should be cleared
IN MIOS_LCD_OPTION1 - contains the first LCD option given by MIOS_LCD_TypeSet
MIOS_LCD_OPTION2 - contains the second LCD option given by MIOS_LCD_TypeSet
OUT -
NOTE see the custom_lcd_example for further details
Back to the top

USER_LCD_Cmd
FUNCTION USER_LCD_Cmd
DESCRIPTION sends a command to the LCD display.
On CLCDs: use this function to decode the HD44780 commands if required
On GLCDs: ignore this function!
IN command which should be sent
OUT -
NOTE see the custom_lcd_example for further details
Back to the top

USER_LCD_CursorSet
FUNCTION USER_LCD_CursorSet
DESCRIPTION This function is called by MIOS when the cursor should be changed
IN MIOS_LCD_OPTION1 - contains the first LCD option given by MIOS_LCD_TypeSet
MIOS_LCD_OPTION2 - contains the second LCD option given by MIOS_LCD_TypeSet
MIOS_GLCD_CURSOR_X - horizontal cursor position (for GLCDs)
MIOS_GLCD_CURSOR_X - vertical cursor position (for GLCDs)
MIOS_LCD_CURSOR - character cursor position (for CLCDs)
OUT -
NOTE see the custom_lcd_example for further details
Back to the top

USER_LCD_Data
FUNCTION USER_LCD_Data
DESCRIPTION sends a data value to the LCD display.
On CLCDs: branch directly to USER_LCD_PrintChar
On GLCDs: ignore this function!
IN data which should be sent
OUT -
NOTE see the custom_lcd_example for further details
Back to the top

USER_LCD_Init
FUNCTION USER_LCD_Init
DESCRIPTION This function is called by MIOS when the custom LCD should be initialized
IN MIOS_LCD_OPTION1 - contains the first LCD option given by MIOS_LCD_TypeSet
MIOS_LCD_OPTION2 - contains the second LCD option given by MIOS_LCD_TypeSet
OUT -
NOTE see the custom_lcd_example for further details
Back to the top

USER_LCD_PrintChar
FUNCTION USER_LCD_PrintChar
DESCRIPTION This function is called by MIOS when a character should be print
IN WREG - character
all other MIOS_*LCD_* registers
OUT GLCDs should justify the X/Y cursor position
NOTE see the custom_lcd_example for further details
Back to the top

USER_LCD_SpecialCharInit
FUNCTION USER_LCD_SpecialCharInit
DESCRIPTION see MIOS_CLCD_SpecialCharInit
IN number of special character (0-7) in WREG
pointer to special char pattern in TBLPTR (consists of 8
entries for every character-line)
OUT TBLPTR has to be set to next table entry (TBLPTR+=8)
NOTE see the custom_lcd_example for further details
Back to the top

USER_MIDI_NotifyRx
FUNCTION USER_MIDI_NotifyRx
DESCRIPTION This function is called by MIOS when a MIDI byte has been received. It can be used to monitor the Rx activity or to do any action - e.g. to react on realtime events like MIDI clock (0xf8) with a minimum latency. Note that this is an interrupt service routine! Use FSR2 instead of FSR0 and IRQ_TMPx instead of TMPx -- and make the routine as fast as possible!
IN received byte in WREG
OUT -
ISR yes
Back to the top

USER_MIDI_NotifyTx
FUNCTION USER_MIDI_NotifyTx
DESCRIPTION This function is called by MIOS before the transfer of a MIDI byte. It can be used to monitor the Tx activity or to do any other actions (e.g. to switch a pin for multiplexed MIDI Outs) before the byte will be sent. Note that this is an interrupt service routine! Use FSR2 instead of FSR0 and IRQ_TMPx instead of TMPx -- and make the routine as fast as possible!
IN transmitted byte in WREG
OUT -
ISR yes
Back to the top

USER_MPROC_DebugTrigger
FUNCTION USER_MPROC_DebugTrigger
DESCRIPTION This function is called by MIOS when a debug command has been received via SysEx
IN WREG, MIOS_PARAMETER1, MIOS_PARAMETER2, MIOS_PARAMETER3 like
specified in the debug command
OUT return values WREG, MIOS_PARAMETER1, MIOS_PARAMETER2, MIOS_PARAMETER3
ISR no
Back to the top

USER_MPROC_NotifyFoundEvent
FUNCTION USER_MPROC_NotifyFoundEvent
DESCRIPTION This function is called by MIOS when a MIDI event has been received which has been specified in the CONFIG_MIDI_IN table
IN number of entry in WREG
first MIDI event byte in MIOS_PARAMETER1
second MIDI event byte in MIOS_PARAMETER2
third MIDI event byte in MIOS_PARAMETER3
OUT -
ISR no
Back to the top

USER_MPROC_NotifyReceivedByte
FUNCTION USER_MPROC_NotifyReceivedByte
DESCRIPTION This function is called by MIOS when a MIDI byte has been received
IN received MIDI byte in WREG and MIOS_PARAMETER1
OUT -
ISR no
Back to the top

USER_MPROC_NotifyReceivedEvent
FUNCTION USER_MPROC_NotifyReceivedEvent
DESCRIPTION This function is called by MIOS when a complete MIDI event has been received
IN first MIDI event byte in MIOS_PARAMETER1
second MIDI event byte in MIOS_PARAMETER2
third MIDI event byte in MIOS_PARAMETER3
OUT -
ISR no
Back to the top

USER_MPROC_NotifyTimeout
FUNCTION USER_MPROC_NotifyTimeout
DESCRIPTION This function is called by MIOS when a MIDI event has not been completly received within 2 seconds
IN -
OUT -
ISR no
Back to the top

USER_SR_Service_Finish
FUNCTION USER_SR_Service_Finish
DESCRIPTION This function is called by MIOS after the shift register have been loaded.
Note that this is an interrupt service routine! Use FSR2 instead of FSR0 and IRQ_TMPx instead of TMPx -- and make the routine as fast as possible!
IN -
OUT -
ISR yes
Back to the top

USER_SR_Service_Prepare
FUNCTION USER_SR_Service_Prepare
DESCRIPTION This function is called by MIOS before the shift register are loaded.
Note that this is an interrupt service routine! Use FSR2 instead of FSR0 and IRQ_TMPx instead of TMPx -- and make the routine as fast as possible!
IN -
OUT -
ISR yes
Back to the top

USER_Tick
FUNCTION USER_Tick
DESCRIPTION This function is called by MIOS in the mainloop when nothing else is to do
IN -
OUT -
ISR no
Back to the top

USER_Timer
FUNCTION USER_Timer
DESCRIPTION This function is periodically called by MIOS. The frequency has to be initialized with MIOS_Timer_Set
Note that this is an interrupt service routine! Use FSR2 instead of FSR0 and IRQ_TMPx instead of TMPx -- and make the routine as fast as possible!
IN -
OUT -
ISR yes
Back to the top


Last update: 2015-09-24

Copyright 1998-2015, Thorsten Klose. All rights reserved.