rn42: Update doc

2 files changed, 404 insertions, 35 deletions

diff --git a/keyboard/hhkb_rn42/MEMO.txt b/keyboard/hhkb_rn42/rn42/MEMO.txt
index f2aaa7c046..f772c4cb53 100644
--- a/keyboard/hhkb_rn42/MEMO.txt
+++ b/keyboard/hhkb_rn42/rn42/MEMO.txt
@@ -1,38 +1,8 @@
-Roving RN-42
-============
+Memo of deveopment
+==================
+just memo, NOT WORTH READING
 
 Bug:
-- with Nexus5 keyboard and mouse are very laggy.
-
-- lose USB connection during power-down mode - DONE
-    - USB initialize code in main() causes this - WRONG
-    - Do not power-down during USB connection is active - DONE 11/11
-        (USB_DeviceState == USB_DEVICE_Configured) is used to check USB connection
-        matrix_power_down() matrix.c - 11/23
-
-- When given power only from wall wart adapter
-    - it sleeps. it should not sleep
-    - Configured state without USB connection?
-
-- timer is slow while power down - DONE 11/26
-    - time out interrupt is lost while power down?
-    - interrupt of watchdog timer compensates timer counter(avr/suspend.c)
-
-- USB plug-in fails while BT
-    - it ends in suspend state
-    - maybe, not responsive to host enumeration process due to power-down.
-    - matrix_power_down() only when state is unattached - 11/26
-        - need to observe a while
-- repeated CHARGING/FULL_CHARGED
-    - In LTC sharp pulses are observed.
-    - MCP has no pulse but still has a problem.
-    - needs more wait before read pin state? - NO
-- wrongly suspended when powered from adapter without USB connection - DONE
-    - suspend event may occur when plug into adapter
-    - and never wake until conected to real USB line
-    - without debug print via USB no problem; CSW(wake just after suspend as real USB line)
-    - seems like USB print causes this problem after suspended
-
 - Factory Reset PIO4 doesn't work
     - the reason is unclear - 12/08 NOT LOOK INTO ANY MORE
     - WORKAROUND: use serial pins(3.3V, GND, RX and TX)
@@ -51,11 +21,9 @@ Todo:
     - no buffering. character lost can be caused.
 - LUFA sendchar should be buffered and serial_uart.c buffur size is too large(256).
 
-- switch BT host connections
 - BT operations
     - disconnect
     - new connection
-    - switch next connection
     - remove connection
 
 - sendchar() in lufa.c block loop   - DONE 11/29
@@ -246,3 +214,42 @@ Done:
 - Under voltage lock out UVLO for protection of Lipo - Lipo has discharge protection at 3.100V    07.01
 - Power saving: HHKB scan, BT radio control - 9h with 850mAh, this is enough   07.01
 - Power selector doesn't work; Q4 MOSFET leaks from Lipo to USB power line. -- use Schottky instead 07/04
+
+- wrongly suspended when powered from adapter without USB connection - DONE
+    - suspend event may occur when plug into adapter
+    - and never wake until conected to real USB line
+    - without debug print via USB no problem; CSW(wake just after suspend as real USB line)
+    - seems like USB print causes this problem after suspended
+
+- lose USB connection during power-down mode - DONE
+    - USB initialize code in main() causes this - WRONG
+    - Do not power-down during USB connection is active - DONE 11/11
+        (USB_DeviceState == USB_DEVICE_Configured) is used to check USB connection
+        matrix_power_down() matrix.c - 11/23
+
+- with Nexus5 keyboard and mouse are very laggy.
+    Not confirmed. 01/15
+
+- switch BT host connections    - CANCEL 01/15
+    - switch next connection
+        cannot switch connection with version 6.15 at least
+
+- When given power only from wall wart adapter  - DONE? not confirmed 01/15
+    - it sleeps. it should not sleep
+    - Configured state without USB connection?
+
+- timer is slow while power down - DONE 11/26
+    - time out interrupt is lost while power down?
+    - interrupt of watchdog timer compensates timer counter(avr/suspend.c)
+
+- repeated CHARGING/FULL_CHARGED    - No longer problem 01/15
+    - In LTC sharp pulses are observed.
+    - MCP has no pulse but still has a problem.
+    - needs more wait before read pin state? - NO
+
+- USB plug-in fails while BT        - No longer problem 01/15
+    - it ends in suspend state
+    - maybe, not responsive to host enumeration process due to power-down.
+    - matrix_power_down() only when state is unattached - 11/26
+        - need to observe a while
+
diff --git a/keyboard/hhkb_rn42/rn42/RN42.txt b/keyboard/hhkb_rn42/rn42/RN42.txt
new file mode 100644
index 0000000000..ace30da4ed
--- /dev/null
+++ b/keyboard/hhkb_rn42/rn42/RN42.txt
@@ -0,0 +1,362 @@
+RN-42 Bluetooth Module Support
+==============================
+Bluetooth controller board works with HHKB Pro2, JP, Type-S and Type-S JP and it supports both USB and Bluetooth as keyboard output protocol. Bluetooth module Roving Networks/Microchip RN-42 is installed on the board.
+
+
+Limitations:
+- short battery life
+- connection switching
+    the module always connects to the last linked device. Remote address setting does not work as expected.
+- HHKB JP requires case modification for power switch and LEDs.
+    without switch power controlled by MCU? Probably using 3.3V regulator enable pin power of RN-42 can be controlled.
+- Wiress certification of RN-42
+    Japan, Korea, Taiwan, Europe, FCC, Canada
+    http://www.microchip.com/wwwproducts/Devices.aspx?product=RN42
+
+NOTE:
+- Lipo battery is not included. Cannot ship it from Japan due to regulations.
+
+Bugs:
+
+Todos:
+
+
+
+
+
+LED Status
+----------
+Configuring                     10 times per sec
+Startup/configuration timer     2 times per sec
+Discoverable/Inquiring/Idle     once per sec
+Connected                       solid on
+
+
+RN-42 Magic Command
+--------------------
+Magic key combination is 'LShift+RShift' by default in case of HHKB.
+
+Here is help.
+
+    ----- Bluetooth RN-42 Help -----
+    i:       RN-42 info
+    b:       battery voltage
+    Del:     enter/exit RN-42 config mode
+    Slck:    RN-42 initialize
+    p:       pairing
+    u:       toggle Force USB mode
+
+    RN-42 info:             displays information of the module on console.
+    battery voltage:        displays current voltage of battery and uptime.
+    RN-42 initialize:       does factory reset and configures RN-42
+    pairing:                enters Pairing mode.
+    toggle Force USB mode:  switch between USB and Bluetooth
+
+
+RN-42 Config mode
+-----------------
+You can tune/operate RN-42 yourself with config(command) mode.
+
+1. hook up USB cable
+2. run `hid_listen` command  in console
+3. turn on Bluetooth switch
+4. press LShift+RShift+Delete(Fn+~) you will see output like followings:
+
+    Entering config mode ...
+    CMD
+    v
+    Ver 6.15 04/26/2013
+    (c) Roving Networks
+
+5. do config with RN-42 commands. See documentations of RN-42.
+6. to exit also press LShift+RShift+Delete(Fn+~)
+
+    Exiting config mode ...
+    ---
+    END
+
+
+RN-42 Initial Configuration
+---------------------------
+RN-42 is configured as SPP device at factory reset, you need to configure it as HID device. This is needed just once first time.
+
+1. hook up USB cable
+2. run `hid_listen` command  in console
+3. turn on Bluetooth switch
+4. press LShift+RShift+ScrLk(Fn+O) you will see output like followings:
+
+    Entering config mode ...
+    CMD
+    Ver 6.15 04/26/2013
+    (c) Roving Networks
+    ECHO ON
+    SF,1
+    AOK
+    S-,TmkBT
+    AOK
+    SS,Keyboard/Mouse
+    AOK
+    SM,4
+    AOK
+    SW,8000
+    AOK
+    S~,6
+    AOK
+    SH,003C
+    AOK
+    SY,FFF4
+    AOK
+    R,1
+    Reboot!
+    Exiting config mode ...
+
+5. output of command 'X' after cofiguration
+
+    Ver 6.15 04/26/2013
+    (c) Roving Networks
+    ***Settings***
+    BTA=00066667BBE9
+    BTName=TmkBT-BBE9
+    Baudrt(SW4)=115K
+    Mode  =DTR 
+    Authen=1
+    PinCod=1234
+    Bonded=0
+    Rem=NONE SET
+    ***ADVANCED Settings***
+    SrvName= Keyboard/Mouse
+    SrvClass=0000
+    DevClass=1F00
+    InqWindw=0100
+    PagWindw=0100
+    CfgTimer=255
+    StatuStr=NULL
+    HidFlags=3c
+    DTRtimer=8
+    KeySwapr=0
+    ***OTHER Settings***
+    Profile= HID
+    CfgChar= $
+    SniffEna=8000
+    LowPower=0
+    TX Power=fff4
+    IOPorts= 0
+    IOValues=0
+    Sleeptmr=0
+    DebugMod=0
+    RoleSwch=0
+
+
+Switch to USB mode
+------------------
+You can switch between USB and Bluetooth with pressing 'LShift+RShift+u'.
+
+
+Pairing mode
+------------
+This disconnects current connect and enter pairing mode.
+
+
+
+
+For deveropment
+===============
+
+RN-42 Serial Connection
+-----------------------
+UART:           115200bps, 8bit, 1-stopbit, non-parity, no flow control
+SSP:            115200bps, 8bit, 1-stopbit, non-parity, no flow control(via Bluetooth)
+
+To enter command mode disconnect the module from host and type '$$$'.(you will see 'CMD') and type '+' to get local echo. To exit type '---'(you will see 'END').
+
+
+RN-42 Commands
+--------------
+S-,tmkBT            // Device name
+SS,keyboard/mouse   // service name
+SM,4                // Auto Connect DTR mode
+SW,8010             // Sniff enable 0x10*0.625ms=10ms; 50ms is laggish and not much power save
+S~,6                // HID profile
+S~,0                // SPP profile
+SH,003C             // HID register
+SY,0004             // Transmit power
+SC,0000             // COD: 000005C0    (see HID spec/Bluegiga doc)
+SD,05C0             //     bit 12-8         7           6           5-0
+                    //         00101        1           1           0
+                    //         peripheral   pointing    keybaord    joystick, gamepad, ...
+SM,6                // Pairing mode: auto connect
+SM,4                // Master mode: Connection can be controled with GPIO6
+SF,1                // Factroy reset
+R,1                 // reboot
+SR,Z                // removes all remote addresses for reconnecting.
+                    // can be used to connect another host
+SR,I                // registers last inquiry address
+
+
+Operation Modes
+---------------
+SM,3        Auto Connect Master mode
+SM,4        Auto Connect DTR Mode uses GPIO6 to make and break connection(Mode =DTR)
+                confirm: auto connect works and control connection with GPIO6
+SM,5        Auto Connect ANY Mode (Mode =ANY)
+                each time GPIO is set, make inquiry and connect to the first found device
+SM,6        automatically reconnect(Mode =Pair)
+                confirm: auto connect works well but difficult to enter command mode.
+
+
+HID flag register
+-----------------
+SH,0200
+GH
+
+10 0000 0000(0200)  default
+00 0011 1000(0038)  Combo
+|| |  | |\_\____ number of paired devices to which the module can reconnect
+|| |  | \_______ send out reports over UART (0xFF <len> <data>)
+|| \__\_________ descriptor type
+|\______________ toggle virtual keyboard on iOS when first connected
+\_______________ Force HID mode if GPIO11 is high on power-up
+
+    Descriptor type:
+    0000:   keybaord
+    0001:   Game Pad
+    0010:   Mouse
+    0011:   Combo
+    0100:   Joystick
+    1xxx:   reserved
+
+
+Out report - Indicator
+----------------------
+0xFE 0x02 0x01 <LED_state>
+
+
+Apple iOS
+---------
+Keyboard can be used with iPhone, but mouse cannot.
+
+
+Android
+-------
+3.7.1.5 Note: To connect with Android phone the modules must wake up 11ms every 2.5seconds.
+
+
+Power Management
+----------------
+Inquiry and Page window     Idle or Active  (3.1.1)
+    Downside: delay in discovery or connection time
+    SI,         // set inquiry scan window(discovery) on/off duty?
+    SJ,         // set page scan window(connection)
+    This reduces averaege power >20mA to 5mA(3mA in Sniff mode)
+
+Sniff mode                  Transmit
+    Sniff mode is disabled by default and radio is active continuously when connected.(25-30mA)
+    In Sniff mode the radio wakes up intermittently and sleeps in very low power mode.(2mA)
+    SW,<val>    // set interval timer(*0.625ms) 0000-7FFF
+
+Deep sleep                  Idle            (3.1.2)
+    In this mode the module shuts down completly and only draws about 300uA. To enable this set the most signifant bit(0x8000) of Sniff interaval timer.
+    SW,8320     // deep sleep enable(interval=0x320*0.625=500ms)
+    In normal sleep the firmware is still running in idle mode, and wakes up about 20 times per second to check ports, update LEDs, etc. During deep sleep, the firmware actually stops runnig some tasks and the LEDs only update about once per second.
+    To wake from deep sleep there are three ways: (in worst case wake up takes 5ms)
+        *send a charactor to the UART(first charactor will be lost)
+        *toggle CTS low to high and wait 5ms
+        *wake automatically every slot time(<val>*0.625ms)
+    Once the radio is awake it stay active for exactly 1 second of inactivity and then sleeps again.
+    Downside: latency and data loss
+
+Disable Output driver       Idle or Active  (3.1.3)
+    S%,1000     // set all GPIO pins(0-11) to inputs.
+
+Lower Transmit Power        Idle or Active  (3.1.4)
+    SY,<hex>    // transmit power setting(takes effect after a power cycle and reboot)
+    Downside: reducing effective range
+
+
+Optimizig for Latency
+---------------------
+By default the firmware is optimized for throughput.
+SQ,16           // set latency bit
+SQ,0            // unset latency bit
+
+
+Configuration timer settings
+----------------------------
+Remote configuration is used for the module to be configured with various commands over Bluetooth(SPP profile only?).
+
+The module has remote configuration timer to allow remote configuration over Bluetooth after power up in Slave mode. In Master modes the remote configuration timer is set to 0(no remote configuration). (In Trigger Master mode the timer is used as an idle timer to break the connection after time expires with no charactors receive.)
+    ST,0        // no remote, no local when connected
+    ST,<1-252>  // local and remote with timeout in seconds from power up
+    ST,253      // local only       without timeout
+    ST,254      // remote only      without timeout
+    ST,255      // local and remote without timeout
+
+
+Commands
+--------
+S7,                     7bit mode
+SA,                     Authenticaiton
+SB,                     Send break
+SC,                     Service class
+SD,                     Device class
+SM,<val>                Operation mode
+SP,<string>             Pin code(alpahnumeric)
+SQ,<mask>               Special configuration(GPIO, discovery mode, low latency, reboot, UART)
+SR,<hex>                Store remote address
+SR,Z                    Erase all address
+SS,<string>             Set service name(1-20)**
+ST,<val>                Remote configuration timer(Master:0, Slave:0-255, Triger:as idle timer)
+SU,<val>                UART baud rate
+SW,<val>                low-power sniff mode** deep sleep and wake up every 625us * <val>
+SX,<0|1>                bonding enable  only acceps device that matches the stored address
+SY,<hex>                power setting**
+SZ,<val>                non-standard raw baud rate  <val>=baud*0.004096
+S~,<val>                Profile     0:SPP, 5:APL, 6:HID
+S-,<string>             Device name     -15 alphanumeric charactors
+S?,<0|1>                role switch enable
+S$,<char>               command mode char
+$|,<hex>                low-power connect mode  deep sleep/active(discoverable and connectable) cycle
+D                       display basic setting
+E                       display extended setting
+GB                      display the device's Bluetooth address
+GF                      display Bluetooth address of connected device
+GK                      show connection status
+GR                      show remote address for reconnecting
+G&                      show GPIO pin
+G<char>                 show stored setting
++                       toggle local echo on/off
+&                       show GPIO 3,4,6,7(DIP switch)
+C                       connect to stored remote address
+C,<address>             connect last address
+CFI                     connect and go into fast data mode
+CFR                     connect and go into fast data mode
+CT,<address>,<val>      connect to the address and disconnect after val?
+F,1                     fast data mod:
+H                       display help
+I,<time>,<cod>          inquiry scan with <cod>
+IN,<time>,<cod>         inquiry scan with <cod>, return without BT name
+IR                      inquiry scan with 0055AA
+IS                      inquiry scan with 001F00
+J                       hide pin code
+K,                      kill    disconnects current connection
+L                       link quality
+M                       show modem signlal status
+O                       display other settings
+P,<char>                pass through?
+Q                       quiet mode  make the module not discoverable
+Q,0                     discoverable and connectable
+Q,1                     not discoverable and not connectable
+Q,2                     not discoverable and connectable
+Q,?                     display current quiet mode
+R,1                     reboot
+T,<0|1>                 pass received data while in command mode
+U,<baud>,<parity>       change UART setting tentatively
+V                       display firmware version
+W                       wake from quiet mode    enable discovery and connection
+Z                       deep sleep mode(<2mA)
+
+
+Reset to Factory Default
+------------------------
+SF,1
+R,1