<commit_before># Bluetooth LED VU bar Documentation

The LED VU bar is a battery powered Bluetooth microcontroller. The
microcontroller responds to serial commands sent from any Bluetooth master and
operates the 5 green LEDs accordingly. The VU bar has an internal Li-Ion
battery which should last between 6 and 40 hours depending on how many LEDs are
lit. The battery will be continuously charged by the solar panel if in the
presence of sunlight. If a faster charge is needed, there is a USB Mini port on
the bottom of the unit. It can be plugged into any computer USB port or AC USB
power adapter. The unit will consume up to ~500mA of current to charge it's
internal battery.

## Contributors

The HUD was originally dreamed up at Ford for use with the [OpenXC][openxc]
project and it was prototyped by the folks at [Bug Labs][buglabs]. The original
software for OSGi was ported to Android by <NAME> at Ford.

[openxc]: http://openxcplatform.com
[buglabs]: http://www.buglabs.net/

## Android

The HUD is exposed in Android via an in-process service. Take a look at the
`HudTestActivity` for an example of how to use it - the test runs a KITT-style
LED fade on the HUD.

To build and deploy the test app to an attached Android device, make sure you
have Maven installed and run:

    $ cd java
    $ mvn install && mvn -pl test android:deploy

### Pairing

In Android, you will need to pair and authenticate with the HUD at least once
before it can be used with the `HudService`. The service doesn't attempt to do
any authentication at the moment, so it must be done by hand.

When powered on, the unit will be a discoverable Bluetooth device. In the
Android "Bluetooth Settings" activity, you should be able to scan for an find a
device named "RN42-XXXX" where XXXX is the last 4 digits of the unit MAC
address.

If the Bluetooth device isn't visible, the unit is either currently connected to
a different Bluetooth master, or the battery has run out of charge. The battery
can be charged while running, so when in doubt connect the LED VU bar to a USB
power source while testing.

## Desktop Testing

For testing purposes, the LED VU bar can also be communicated by a computer with
a Bluetooth adapter. We have tested this in Ubuntu 10.10 with an integrated
Bluetooth adapter. In theory, any computer that can connect to the SPP profile
on a Bluetooth device can work. Our steps for communicating with the device
directly:

1. Install blueman by entering "sudo apt-get install blueman" into a terminal
2. Launch blueman via `System->Preferences->Bluetooth Manager`
3. Click the "Search" button. After a minute, you should see an entry with the
   name "RN42-XXXX". If blueman is having trouble resolving device names, you
   may see a device with a MAC address starting with "00:06:66".
4. Right click on the RN42 device and click "pair". When prompted, enter
   "1234".
5. Right click on the RN42 device and click SPP. If successfull, blueman will
   create a message "Serial port connected to /dev/rfcommX"
6. In a terminal, enter "echo 'S0255' > /dev/rfcommX" where "rfcommX" is the
   device indicated in step 5. You should see LED1 turn on
7. Enter "echo 'S00' > /dev/rfcommX" to turn the LED back off
8. Enter "echo 'B' > /dev/rfcommX && cat /dev/rfcomm1". You should see
   "VAL:XXX" where XXX is the raw battery voltage. The battery should be close
   to 655 when full, and should drain down to approximately 413. It is a
   highly non-linear scale. Press Control-C.

To communicate directly with the device, you can send strings terminated with
either `\n` or `M`. The following commands are accepted:

```
'P' - Ping the device. No arguments. Device should respond with "ACK"
'B' - Check raw battery level. No arguments. Device should respond with
    "VAL:XXX" where XXX is the raw ADC value 0-1023 corresponding to
    approximately 0V - 1.63V
'S' - Set a channel. Arguments are `[channel][intensity]`. Channel is a single
    character, 0-4. Intensity is a value 0-255, expressed as a string.
    Example: "S2255" (set chan 2 at full) "S00" (turn off chan 0)  "S4128" (set
    chan 4 to about half)
'F' - Fade a channel from its current value to a destination value. Arguments
    are `[channel][duration(ms)],[intensity]`. Duration is a value from
    0-65535, expressed as a string (in the unit of ms). Example: "F12000,255"
    (fade channel 1 to full over 2 seconds)
```

For additional troubleshooting, there are two LEDs on the circuit board within
the LED VU bar. LED6 (located just alongside the RN-42 chip) will blink when
the Bluetooth chipset is discoverable, and will turn off when connected. LED7
(opposite the RN42 from LED6, just behind the DC power jack) illustrates charge
status. It will be lit solidly while charging, and will start to blink or dim
as charging is completed. Unfortunately, the housing must be removed in order
to get a clear view of these LEDs.

The LED VU bar board can also be programmed as a Bluetooth arduino. Once
connected to the SPP profile (step 5 above), the /dev/rfcommX port must be
softlinked to a normal serial port in order for some versions of the arduino IDE
to detect it. try "ln -s /dev/rfcommX /dev/ttyS50". You may need to run
arduino with root permissions "sudo arduino". Make sure to select "Arduino Pro
or Pro Mini (3.3V, 8 MHz) w/ATmega328" as the Board, and "ttyS50" as the Serial
Port. You should be able to use the Serial Monitor to communicate with the
device - make sure to use a version of the arduino IDE that has a line ending
selector dropdown box to the left of the baud rate dropdown box - select
"newline".

If for whatever reason the RN42 chip gets reset to factory default settings,
there are a few configuration options to change. Power down the board (by
disconnecting USB and battery) and then reconnect it. Within 1 minute, connect
to the RN42 and send "$$$". You should see "CMD" in response, and LED6 should
blink quickly. Then enter the following commands, followed by enter (or '\n'):

    SU,57600
    S~,3
    ST,255

After each command, you should see "AOK" in response. After the last command,
you should see "END" and LED6 should cease blinking. Power cycle the board
again (by disconnecting and reconnecting the battery) and the RN42 should be
able to communicate with the microcontroller.

## Hardware

The LED VU is controlled by IC2, an ATMEGA 328P 8-bit microprocessor. The
ATMEGA communicates with a PC, Phone or Bug Base using Bluetooth via IC1. IC1
is a Roving Networks RN-42, a common embedded Bluetooth IC. They communicate
using a serial UART bus. When a host connects to the RN-42, it transparently
relays serial data between the ATMEGA and the PC, Phone or Bug.

Capacitors C1 and C4 allow the ATMEGA to be remotely reset by briefly asserting
the DTR or CTS lines of the RN-42. With the accompanying bootloader, this
allows the ATMEGA to function like a Bluetooth arduino. The first time an LED
VU board is assembled, the arduino bootloader needs to be installed. This can
be accomplished with an AVR programmer and the ICSP port (J1). As long as the
RN-42 is correctly configured (see above), code can be deployed to the ATMEGA.

The ATMEGA is connected to LED1-5 using arduino pins 3,5,6,9 and 10, or
PORTD3,5,6 and PORTB1,2. The LEDS are lit using generic NPN transistors Q2-6,
since the specified LEDs are high-intensity and require too much current for the
pins on the ATMEGA. Note that the values of R1-R10 depend on the desired
intensity level. 75 ohms is a conservative value - to get maximum intensity out
of the specified LEDs we needed to use 0 ohm jumpers.

The AVR, RN-42 and LEDs are all powered by a lithium-ion battery connected to
JP1. The battery power is regulated to 3.3v by U2, a boost converter. This
allows us to drain the maximum amount of power from the battery without damaging
it (the regulator has a 2.6V cutoff). The battery can power the circuit for
many hours depending on the LED usage (anywhere from 6-48 hours).

The battery can be charged from either a USB Mini power source or the attached
solar panel. The USB power source is the optimal way to charge the battery - it
will charge at the maximum rate of 500mA provided that much power is available.
The DC jack is designed to be used with a 6V solar panel like those available
from Adafruit.com. The Li-Ion charger (U1, an MCP73831) isn't designed to take
power from a variable impediance source like a solar cell, but with a large
input cap (C9) the circuit is reasonably good at harvesting solar power. See
ladyada's writeup on MPPT for her solarlipo charger project
(http://ladyada.net/products/usbdcsolarlipo/design.html).

With the small solar panel installed on the LED VU board, we measured between
100-200mA under direct sunlight. A larger solar panel would be able to get
closer to the 500mA maximum charge rate. If all of the LEDs are fully lit all
the time, the LED board needs to be under direct sunlight in order to actually
charge the battery.
<commit_msg>change name from LED VU bar to Bluetooth HUD<commit_after># Bluetooth HUD Documentation

The Bluetooth HUD is a battery powered Bluetooth microcontroller. The
microcontroller responds to serial commands sent from any Bluetooth master and
operates the 5 green LEDs accordingly. The Bluetooth HUD an internal Li-Ion
battery which should last between 6 and 40 hours depending on how many LEDs are
lit. The battery will be continuously charged by the solar panel if in the
presence of sunlight. If a faster charge is needed, there is a USB Mini port on
the bottom of the unit. It can be plugged into any computer USB port or AC USB
power adapter. The unit will consume up to ~500mA of current to charge it's
internal battery.

## Contributors

The HUD was originally dreamed up at Ford for use with the [OpenXC][openxc]
project and it was prototyped by the folks at [Bug Labs][buglabs]. The original
software for OSGi was ported to Android by <NAME> at Ford.

[openxc]: http://openxcplatform.com
[buglabs]: http://www.buglabs.net/

## Android

The HUD is exposed in Android via an in-process service. Take a look at the
`HudTestActivity` for an example of how to use it - the test runs a KITT-style
LED fade on the HUD.

To build and deploy the test app to an attached Android device, make sure you
have Maven installed and run:

    $ cd java
    $ mvn install && mvn -pl test android:deploy

### Pairing

In Android, you will need to pair and authenticate with the HUD at least once
before it can be used with the `HudService`. The service doesn't attempt to do
any authentication at the moment, so it must be done by hand.

When powered on, the unit will be a discoverable Bluetooth device. In the
Android "Bluetooth Settings" activity, you should be able to scan for an find a
device named "RN42-XXXX" where XXXX is the last 4 digits of the unit MAC
address.

If the Bluetooth device isn't visible, the unit is either currently connected to
a different Bluetooth master, or the battery has run out of charge. The battery
can be charged while running, so when in doubt connect the LED VU bar to a USB
power source while testing.

## Desktop Testing

For testing purposes, the Bluetooth HUD can also be communicated by a computer with
a Bluetooth adapter. We have tested this in Ubuntu 10.10 with an integrated
Bluetooth adapter. In theory, any computer that can connect to the SPP profile
on a Bluetooth device can work. Our steps for communicating with the device
directly:

1. Install blueman by entering "sudo apt-get install blueman" into a terminal
2. Launch blueman via `System->Preferences->Bluetooth Manager`
3. Click the "Search" button. After a minute, you should see an entry with the
   name "RN42-XXXX". If blueman is having trouble resolving device names, you
   may see a device with a MAC address starting with "00:06:66".
4. Right click on the RN42 device and click "pair". When prompted, enter
   "1234".
5. Right click on the RN42 device and click SPP. If successfull, blueman will
   create a message "Serial port connected to /dev/rfcommX"
6. In a terminal, enter "echo 'S0255' > /dev/rfcommX" where "rfcommX" is the
   device indicated in step 5. You should see LED1 turn on
7. Enter "echo 'S00' > /dev/rfcommX" to turn the LED back off
8. Enter "echo 'B' > /dev/rfcommX && cat /dev/rfcomm1". You should see
   "VAL:XXX" where XXX is the raw battery voltage. The battery should be close
   to 655 when full, and should drain down to approximately 413. It is a
   highly non-linear scale. Press Control-C.

To communicate directly with the device, you can send strings terminated with
either `\n` or `M`. The following commands are accepted:

```
'P' - Ping the device. No arguments. Device should respond with "ACK"
'B' - Check raw battery level. No arguments. Device should respond with
    "VAL:XXX" where XXX is the raw ADC value 0-1023 corresponding to
    approximately 0V - 1.63V
'S' - Set a channel. Arguments are `[channel][intensity]`. Channel is a single
    character, 0-4. Intensity is a value 0-255, expressed as a string.
    Example: "S2255" (set chan 2 at full) "S00" (turn off chan 0)  "S4128" (set
    chan 4 to about half)
'F' - Fade a channel from its current value to a destination value. Arguments
    are `[channel][duration(ms)],[intensity]`. Duration is a value from
    0-65535, expressed as a string (in the unit of ms). Example: "F12000,255"
    (fade channel 1 to full over 2 seconds)
```

For additional troubleshooting, there are two LEDs on the circuit board within
the Bluetooth HUD. LED6 (located just alongside the RN-42 chip) will blink when
the Bluetooth chipset is discoverable, and will turn off when connected. LED7
(opposite the RN42 from LED6, just behind the DC power jack) illustrates charge
status. It will be lit solidly while charging, and will start to blink or dim
as charging is completed. Unfortunately, the housing must be removed in order
to get a clear view of these LEDs.

The Bluetooth HUD can also be programmed as a Bluetooth arduino. Once
connected to the SPP profile (step 5 above), the /dev/rfcommX port must be
softlinked to a normal serial port in order for some versions of the arduino IDE
to detect it. try "ln -s /dev/rfcommX /dev/ttyS50". You may need to run
arduino with root permissions "sudo arduino". Make sure to select "Arduino Pro
or Pro Mini (3.3V, 8 MHz) w/ATmega328" as the Board, and "ttyS50" as the Serial
Port. You should be able to use the Serial Monitor to communicate with the
device - make sure to use a version of the arduino IDE that has a line ending
selector dropdown box to the left of the baud rate dropdown box - select
"newline".

If for whatever reason the RN42 chip gets reset to factory default settings,
there are a few configuration options to change. Power down the board (by
disconnecting USB and battery) and then reconnect it. Within 1 minute, connect
to the RN42 and send "$$$". You should see "CMD" in response, and LED6 should
blink quickly. Then enter the following commands, followed by enter (or '\n'):

    SU,57600
    S~,3
    ST,255

After each command, you should see "AOK" in response. After the last command,
you should see "END" and LED6 should cease blinking. Power cycle the board
again (by disconnecting and reconnecting the battery) and the RN42 should be
able to communicate with the microcontroller.

## Hardware

The LED VU is controlled by IC2, an ATMEGA 328P 8-bit microprocessor. The
ATMEGA communicates with a PC, Phone or Bug Base using Bluetooth via IC1. IC1
is a Roving Networks RN-42, a common embedded Bluetooth IC. They communicate
using a serial UART bus. When a host connects to the RN-42, it transparently
relays serial data between the ATMEGA and the PC, Phone or Bug.

Capacitors C1 and C4 allow the ATMEGA to be remotely reset by briefly asserting
the DTR or CTS lines of the RN-42. With the accompanying bootloader, this
allows the ATMEGA to function like a Bluetooth arduino. The first time an LED
VU board is assembled, the arduino bootloader needs to be installed. This can
be accomplished with an AVR programmer and the ICSP port (J1). As long as the
RN-42 is correctly configured (see above), code can be deployed to the ATMEGA.

The ATMEGA is connected to LED1-5 using arduino pins 3,5,6,9 and 10, or
PORTD3,5,6 and PORTB1,2. The LEDS are lit using generic NPN transistors Q2-6,
since the specified LEDs are high-intensity and require too much current for the
pins on the ATMEGA. Note that the values of R1-R10 depend on the desired
intensity level. 75 ohms is a conservative value - to get maximum intensity out
of the specified LEDs we needed to use 0 ohm jumpers.

The AVR, RN-42 and LEDs are all powered by a lithium-ion battery connected to
JP1. The battery power is regulated to 3.3v by U2, a boost converter. This
allows us to drain the maximum amount of power from the battery without damaging
it (the regulator has a 2.6V cutoff). The battery can power the circuit for
many hours depending on the LED usage (anywhere from 6-48 hours).

The battery can be charged from either a USB Mini power source or the attached
solar panel. The USB power source is the optimal way to charge the battery - it
will charge at the maximum rate of 500mA provided that much power is available.
The DC jack is designed to be used with a 6V solar panel like those available
from Adafruit.com. The Li-Ion charger (U1, an MCP73831) isn't designed to take
power from a variable impediance source like a solar cell, but with a large
input cap (C9) the circuit is reasonably good at harvesting solar power. See
ladyada's writeup on MPPT for her solarlipo charger project
(http://ladyada.net/products/usbdcsolarlipo/design.html).

With the small solar panel installed on the Bluetooth HUD, we measured between
100-200mA under direct sunlight. A larger solar panel would be able to get
closer to the 500mA maximum charge rate. If all of the LEDs are fully lit all
the time, the LED board needs to be under direct sunlight in order to actually
charge the battery.

{'fraction_non_alphanumeric': 0.04992772156121428, 'fraction_numerical': 0.022573112420771712, 'mean_word_length': 3.96878453038674, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7163155', 'n_tokens_mistral': 5313, 'n_tokens_neox': 4829, 'n_words': 3003}