Index:

1. Description
2. Project
3. Calibration
4. Software UART
5. USB keyboard
6. Usage
7. Fuse bytes
_____________________________________________________________________________________________________

1. Description

Receive a complete caller line ID message through the software uart.
The reception of a clid message is alerted to the host by sending a '5' character through the
keyboard end point. It can then be retrieved with a USB control message in Linux CLI as well as
the OSCCAL value which can be set in the same way as well.
_____________________________________________________________________________________________________

2. Project

The project is based on PowerSwitch (https://obdev.at/products/vusb/powerswitch.html)

Used ATtiny45 instead of original device (AT90S2313).

Eliminated crystal by using internal RC oscillator and PLL of ATtiny45 to generate a 16.5 MHz clock
(see fuse bytes below).

This frees two pins: 2 (PB3) and 3 (PB4).
_____________________________________________________________________________________________________

3. Calibration

To be able to use the internal RC oscillator in USB applications its OSCCAL value needs to be
calibrated at startup.

The calibration method used in EasyLogger.2012-12-08 (https://www.obdev.at/products/vusb/easylogger.html)
had to be modified for this device, as the ATTINY45 has two OSCCAL ranges instead of one.

According to the ATtiny45 data sheet:
A pre-programmed calibration value is automatically written to this register
during chip reset, giving the Factory calibrated frequency (...)
(...) The CAL7 bit determines the range of operation for the oscillator.
Setting this bit to 0 gives the lowest frequency range, setting this bit to 1
gives the highest frequency range. The two frequency ranges are overlapping,
in other words a setting of OSCCAL = 0x7F gives a higher frequency
than OSCCAL = 0x80.

So a range must be selected first. This is done by using the pre-programmed calibration
value OSCCAL. This OSCCAL is either in the high range or in the low range. But, if it is a very
low value in the high range the low range is searched as the ranges are overlapping.
Likewise, if it is a very high value in the low range the high range is searched.

As in EasyLogger.2012-12-08 in that range a binary search for the OSCCAL value is performed.
Finally the values just below and above the value found are checked too.

The calibrated value is not stored in EEPROM but used straight away and determined again when
restarted.
_____________________________________________________________________________________________________

4. Software UART

The Software UART is based on https://github.com/blalor/avr-softuart. However these modifications
had to be made:

A. Changed I/O definition in softuart.h

B. A new SOFTUART_PRESCALE == 64 added to softuart.c

C. Added ISR_NOBLOCK attribute to ISR call in softuart.c to give way to USB communication.
	Refer to usbdrv/usbdrv.h:
	Interrupt latency:
	The application must ensure that the USB interrupt is not disabled for more
	than 25 cycles (this is for 12 MHz, faster clocks allow longer latency).
	This implies that all interrupt routines must either have the "ISR_NOBLOCK"
	attribute set (see "avr/interrupt.h") or be written in assembler with "sei"
	as the first instruction.
_____________________________________________________________________________________________________

5. USB keyboard

On the USB bus this device behaves like a USB keyboard. The keyboard event generation is based
on https://codeandlife.com/2012/06/18/usb-hid-keyboard-with-v-usb/.
_____________________________________________________________________________________________________

6. Usage

Can be used by host to trigger an interrupt like this:
while true; do
 # wait for key
 cat /dev/input/event1 | grep -q .
 # retrieve clid message
 tinyclid read
 # process clid message
 # clear clid message
 tinyclid clear
done

Command line tool usage:
  tinyclid testcomm
    Tests the USB communication with the device. Should give "communication test succeeded".
  tinyclid testkey
    This command causes the tinyclid keyboard end point to send a '5' key to the host.
  tinyclid read
    Retrieves the CLID message.
  tinyclid clear
    Clears the CLID message.
  tinyclid getosccal
    Retrieves the current OSCCAL value used by the device to calibrate its internal RC oscillator.
  tinyclid setosccal <OSCCAL>
    Sets the current OSCCAL value used by the device to calibrate its internal RC oscillator.

Refer to readme_openwrt.txt in the commandline folder to find out how to use tinyclid in OpenWrt.
____________________________________________________________________________________________________

7. Fuse bytes

# Fuse high byte:
# 0xdf = 1 1 0 1   1 1 1 1
#        ^ ^ ^ ^   ^ \-+-/ 
#        | | | |   |   +------ BODLEVEL 2..0 (Brown-Out Detection -> disabled)
#        | | | |   +---------- EESAVE (preserve EEPROM on Chip Erase -> not preserved)
#        | | | +-------------- WDTON (watchdog timer always on -> disabled)
#        | | +---------------- SPIEN (enable serial programming -> enabled)
#        | +------------------ DWEN (debug wire enable -> disabled)
#        +-------------------- RSTDISBL (disable external reset -> enabled)
#
# Fuse low byte:
# 0xe1 = 1 1 1 0   0 0 0 1
#        ^ ^ \+/   \--+--/
#        | |  |       +------- CKSEL 3..0 (clock selection -> HF PLL)
#        | |  +--------------- SUT 1..0 (start up time -> slowly rising power)
#        | +------------------ CKOUT (clock output on CKOUT pin -> disabled)
#        +-------------------- CKDIV8 (divide clock by 8 -> don't divide)
____________________________________________________________________________________________________