Getting Started with your Neo 1973

From Openmoko

Revision as of 19:46, 10 August 2007 by Hns (Talk | contribs)

Jump to: navigation, search

Some first steps guide for those who have just received their first Neo1973 hardware

Contents

Hardware

Inserting the battery

Remove the back cover by puting your fingernail in the small recess on the top of the Neo, and pull gently (see just the first step of Disassembling Neo1973).

See notes below on inserting the SIM, the SD card, and the battery (this page needs to be reorganized).

Powering up the phone

bootloader splash screen

Just hitting the power button (depending on your u-boot version you have to press for >= 5 seconds) should get the phone first into the bootloader, then boot the kernel, and get into X/OpenMoko. The shipped battery typically has enough charge to boot up directly without charging through the usb cable first.

Once you have pressed the power button sufficiently long, the vibrator makes a short pulse and the screen backlight turns on. You can now release the power button and watch the phone booting.

If the battery is not sufficiently charged, the phone will not turn on, even if the usb cable is plugged in.

Flashing the Neo1973 GTA01Bv4

The GTA01Bv4 devices that are currently shipping do not boot out of the box. Flashing the phone with the latest kernel and supporting file system ("rootfs") is required before the phone will successfully boot.

Read more information at about Flashing openmoko. MacOS X users please also refer to MacOS_X.

Powering down the phone

While in bootloader mode, or if the phone has crashed

If you press the power button for 9 seconds, the phone will switch off. You can notice this by the backlight going dark.

While running a full linux system with userspace

In this mode, a power-button press of 5 seconds will be sufficient. After this, the init process will take care of safely shutting down the phone, which might take up to 20 extra seconds. The X server should get killed, you should drop back to a (garbled) console, and it should finally switch off - much like a regular Linux PC.

Battery charging

The Neo1973 supports two charging modes: One 100mA charge mode (called pre-charge) and 500mA (called fast charge). Charging is always done via the USB socket. You can use any USB-A to USB-mini-B cable to connect the phone to any USB host.

While in u-boot

While you are in u-boot mode, the phone only charges with 100mA by default. (This will change in one of the future revisions).

However, using the u-boot console you can manually enable fast charging. See U-boot#Battery_charger_related for more information.

While in Linux

As soon as the phone is connected via USB cable, it will charge. However, the default charging current is only 100mA, way too little if you want to operate the phone and charge at the same time.

If your USB upstream port is capable of supplying 500mA, then it will configure the Neo1973 accordingly and use 500mA charging mode. You can notice this by the following line in the kernel log (/var/log/messages) of the laptop/desktop your Neo1973 is hooked up to

usb0: full speed config #1: 500 mA, Ethernet Gadget, using CDC Ethernet

Inserting the SIM card (optional)

The slot is found just under the battery. The card holder has arrows indicating which way to push it to unlock it - make sure you don't open it with force when it's locked or it may break. Insert the SIM so that the pads make contact and push the holder firmly until it makes a click, then lock it - otherwise the card will not be detected.

To check if the SIM card is inserted correctly in Linux, you can have a look in gsmd logs or use the instructions detailed in the Manually using GSM page and issue the AT+CIMI command.

Using your micro-SD card

You should have received a memory card with your phone. You might want to copy some mp3 (or better Ogg Vorbis) files to it to try media playback.

Open the SIM card holder (see above) and gently slide the micro-SD shield toward the battery contacts. Lift up the shield and insert the card, contacts first and away from the shield side. Rotate it shut and gently slide the shield away from the battery contacts to lock it closed.

The card should automatically be available under /media/card the next time you boot. You can test it and your audio drivers at the same time by playing an mp3 from it. See Neo1973 Audio Subsystem.

A small video howto (SIM and microSD) is available on google video: http://video.google.de/videoplay?docid=-8343770443102960945

Getting shell access on the phone

By using the terminal emulator and on-screen keyboard

"Click" (using a stylus) the top-left arrow icon to get a drop-down menu with "Media", "Settings", "Utilities" and "Desktop". Choose "Utilities->Panel->Input Manager", and a keyboard icon will appear on the top bar. You can get an on-screen keyboard at any time by choosing it.

With newer images, the keyboard comes up when you tap the white box in the top bar.

You can choose between different keyboard layouts and the stroke recognizer by dragging from the white box and releasing it to the right of the box.

From the desktop, choose "Active tasks->rxvt" to get a root shell.

Terminal is in the top level menu in recent images.

By using Ethernet emulation over a USB cable

The standard Neo1973 Linux kernel has support for the "cdc_ether USB gadget", i.e. a standard implementation of how to emulate an Ethernet device over USB.

As soon as the kernel is up and running, and you have the phone connected via USB, you should get a usb0 device on your host.

The Phone will have the IPv4 address 192.168.0.202/24. You can run `ifconfig` in the terminal on the phone to verify this (this is optional, just check it if it doesn't work given the instructions below)

If you plug a USB cable into a laptop running Linux, you'll likely see the "cdc_ether" kernel module being loaded and a usb0 network interface appear.

On the host PC, you should then configure your interface to 192.168.0.200 by using

# ifconfig usb0 192.168.0.200 netmask 255.255.255.0

Then you should be able to

# ping 192.168.0.202

and last, but not least

# ssh root@192.168.0.202

Once you press 'enter' (empty password), you should now have a root login.

See USB_Networking for more details, including instructions on how to automatically setup masquerading so that your phone can get access to the internet through the host PC.


By using the debug board/serial/JTAG

Please see Debug Board#Usage_Instructions

Getting access to the bootloader console

Please see u-boot#Using_usbtty_from_Linux

Using Audio

Enable Internal Speaker and Mic in Phone Calls

If you got no Speaker and Mic during a Call you need to load the "gsmhandset.state" alsa-configfile

alsactl -f /etc/alsa/gsmhandset.state restore

Maybe you need to load another .state file for playing mp3 or a BT-Headset see in /etc/alsa/

To hear something you can find an .au file (or convert a .wav into an .au by using the sox tool):

sox ringtone_thereisnophone.wav -t raw -r 8012 -u -b -c 1 rigtone_thereisnophone.au

copy it to the device and run

cat ringtone_thereisnophone.au > /dev/dsp

Useful commands in Linux

Suspending

Writing "mem" into /sys/power/state tells Linux to suspend - it will enter a low power mode where only the GSM and RAM are powered up and the CPU sleeps. It will persist in this state until a wake-up event arrives. Some currently enabled wake-up events are: AUX or POWER key press, USB cable detect.

If you're connected over ssh, sshd will stop responding when the OS suspends, so to avoid locking up your ssh client, use the command

# (sleep 1; echo mem > /sys/power/state) & exit

Initial backup

After getting your new Neo1973 booted for the first time you might want to make a back up of the original flash chip contents on your PC, before you overwrite the flash with a custom image or just update to a newer build.

NOTE: For phase 0 developers only (GTA01Bv4 shippment 0, not > 0 ): This is a good idea because there are parts in the root filesystem that can't be distributed over internet so they are only found in the shipped ROM (see the GPS driver).


One easy way to back up all of the Flash, that doesn't require installing any special software, is with netcat over the USB ethernet. The following commands can be used for that.

On the host On the target
$ netcat -l -p 20000 > mtdblock0
$ netcat -l -p 20000 > mtdblock1
$ netcat -l -p 20000 > mtdblock2
$ netcat -l -p 20000 > mtdblock3
$ netcat -l -p 20000 > mtdblock4
# cat /dev/mtdblock0 | nc 192.168.0.200 20000
# cat /dev/mtdblock1 | nc 192.168.0.200 20000
# cat /dev/mtdblock2 | nc 192.168.0.200 20000
# cat /dev/mtdblock3 | nc 192.168.0.200 20000
# cat /dev/mtdblock4 | nc 192.168.0.200 20000

This stores the five NAND partitions in files named mtdblock*. Knowing the partition layout (u-boot "mtdparts" command or Linux dmesg) you can restore the whole flash with it.

Setting date and time

To set the date and time you need to open a terminal or ssh to the device. To set the date and time to August 9 19:02 2007 type:

# date -s 080919022007

The screensaver might turn on as you execute this command - just tap the screen to get back.

Now, you need to synchronize the time with the hardware date/time by typing:

# hwclock --systohc

Where to from here

You'll probably want to play with some of the interesting hardware in this device. Obviously, you can explore the applications available through the touch-screen interface. But for those who prefer doing things more in the raw from a shell prompt, you can manually use GSM, manually use SMS, or you can start playing with the GPS.

Personal tools

Some first steps guide for those who have just received their first Neo1973 hardware

Hardware

Inserting the battery

Remove the back cover by puting your fingernail in the small recess on the top of the Neo, and pull gently (see just the first step of Disassembling Neo1973).

See notes below on inserting the SIM, the SD card, and the battery (this page needs to be reorganized).

Powering up the phone

bootloader splash screen

Just hitting the power button (depending on your u-boot version you have to press for >= 5 seconds) should get the phone first into the bootloader, then boot the kernel, and get into X/OpenMoko. The shipped battery typically has enough charge to boot up directly without charging through the usb cable first.

Once you have pressed the power button sufficiently long, the vibrator makes a short pulse and the screen backlight turns on. You can now release the power button and watch the phone booting.

If the battery is not sufficiently charged, the phone will not turn on, even if the usb cable is plugged in.

Flashing the Neo1973 GTA01Bv4

The GTA01Bv4 devices that are currently shipping do not boot out of the box. Flashing the phone with the latest kernel and supporting file system ("rootfs") is required before the phone will successfully boot.

Read more information at about Flashing openmoko. MacOS X users please also refer to MacOS_X.

Powering down the phone

While in bootloader mode, or if the phone has crashed

If you press the power button for 9 seconds, the phone will switch off. You can notice this by the backlight going dark.

While running a full linux system with userspace

In this mode, a power-button press of 5 seconds will be sufficient. After this, the init process will take care of safely shutting down the phone, which might take up to 20 extra seconds. The X server should get killed, you should drop back to a (garbled) console, and it should finally switch off - much like a regular Linux PC.

Battery charging

The Neo1973 supports two charging modes: One 100mA charge mode (called pre-charge) and 500mA (called fast charge). Charging is always done via the USB socket. You can use any USB-A to USB-mini-B cable to connect the phone to any USB host.

While in u-boot

While you are in u-boot mode, the phone only charges with 100mA by default. (This will change in one of the future revisions).

However, using the u-boot console you can manually enable fast charging. See U-boot#Battery_charger_related for more information.

While in Linux

As soon as the phone is connected via USB cable, it will charge. However, the default charging current is only 100mA, way too little if you want to operate the phone and charge at the same time.

If your USB upstream port is capable of supplying 500mA, then it will configure the Neo1973 accordingly and use 500mA charging mode. You can notice this by the following line in the kernel log (/var/log/messages) of the laptop/desktop your Neo1973 is hooked up to

usb0: full speed config #1: 500 mA, Ethernet Gadget, using CDC Ethernet

Inserting the SIM card (optional)

The slot is found just under the battery. The card holder has arrows indicating which way to push it to unlock it - make sure you don't open it with force when it's locked or it may break. Insert the SIM so that the pads make contact and push the holder firmly until it makes a click, then lock it - otherwise the card will not be detected.

To check if the SIM card is inserted correctly in Linux, you can have a look in gsmd logs or use the instructions detailed in the Manually using GSM page and issue the AT+CIMI command.

Using your micro-SD card

You should have received a memory card with your phone. You might want to copy some mp3 (or better Ogg Vorbis) files to it to try media playback.

Open the SIM card holder (see above) and gently slide the micro-SD shield toward the battery contacts. Lift up the shield and insert the card, contacts first and away from the shield side. Rotate it shut and gently slide the shield away from the battery contacts to lock it closed.

The card should automatically be available under /media/card the next time you boot. You can test it and your audio drivers at the same time by playing an mp3 from it. See Neo1973 Audio Subsystem.

A small video howto (SIM and microSD) is available on google video: http://video.google.de/videoplay?docid=-8343770443102960945

Getting shell access on the phone

By using the terminal emulator and on-screen keyboard

"Click" (using a stylus) the top-left arrow icon to get a drop-down menu with "Media", "Settings", "Utilities" and "Desktop". Choose "Utilities->Panel->Input Manager", and a keyboard icon will appear on the top bar. You can get an on-screen keyboard at any time by choosing it.

With newer images, the keyboard comes up when you tap the white box in the top bar.

You can choose between different keyboard layouts and the stroke recognizer by dragging from the white box and releasing it to the right of the box.

From the desktop, choose "Active tasks->rxvt" to get a root shell.

Terminal is in the top level menu in recent images.

By using Ethernet emulation over a USB cable

The standard Neo1973 Linux kernel has support for the "cdc_ether USB gadget", i.e. a standard implementation of how to emulate an Ethernet device over USB.

As soon as the kernel is up and running, and you have the phone connected via USB, you should get a usb0 device on your host.

The Phone will have the IPv4 address 192.168.0.202/24. You can run `ifconfig` in the terminal on the phone to verify this (this is optional, just check it if it doesn't work given the instructions below)

If you plug a USB cable into a laptop running Linux, you'll likely see the "cdc_ether" kernel module being loaded and a usb0 network interface appear.

On the host PC, you should then configure your interface to 192.168.0.200 by using

# ifconfig usb0 192.168.0.200 netmask 255.255.255.0

Then you should be able to

# ping 192.168.0.202

and last, but not least

# ssh root@192.168.0.202

Once you press 'enter' (empty password), you should now have a root login.

See USB_Networking for more details, including instructions on how to automatically setup masquerading so that your phone can get access to the internet through the host PC.


By using the debug board/serial/JTAG

Please see Debug Board#Usage_Instructions

Getting access to the bootloader console

Please see u-boot#Using_usbtty_from_Linux

Using Audio

Enable Internal Speaker and Mic in Phone Calls

If you got no Speaker and Mic during a Call you need to load the "gsmhandset.state" alsa-configfile

alsactl -f /etc/alsa/gsmhandset.state restore

Maybe you need to load another .state file for playing mp3 or a BT-Headset see in /etc/alsa/

To hear something you can find an .au file (or convert a .wav into an .au by using the sox tool):

sox ringtone_thereisnophone.wav -t raw -r 8012 -u -b -c 1 rigtone_thereisnophone.au

copy it to the device and run

cat ringtone_thereisnophone.au > /dev/dsp

Useful commands in Linux

Suspending

Writing "mem" into /sys/power/state tells Linux to suspend - it will enter a low power mode where only the GSM and RAM are powered up and the CPU sleeps. It will persist in this state until a wake-up event arrives. Some currently enabled wake-up events are: AUX or POWER key press, USB cable detect.

If you're connected over ssh, sshd will stop responding when the OS suspends, so to avoid locking up your ssh client, use the command

# (sleep 1; echo mem > /sys/power/state) & exit

Initial backup

After getting your new Neo1973 booted for the first time you might want to make a back up of the original flash chip contents on your PC, before you overwrite the flash with a custom image or just update to a newer build.

NOTE: For phase 0 developers only (GTA01Bv4 shippment 0, not > 0 ): This is a good idea because there are parts in the root filesystem that can't be distributed over internet so they are only found in the shipped ROM (see the GPS driver).


One easy way to back up all of the Flash, that doesn't require installing any special software, is with netcat over the USB ethernet. The following commands can be used for that.

On the host On the target
$ netcat -l -p 20000 > mtdblock0
$ netcat -l -p 20000 > mtdblock1
$ netcat -l -p 20000 > mtdblock2
$ netcat -l -p 20000 > mtdblock3
$ netcat -l -p 20000 > mtdblock4
# cat /dev/mtdblock0 | nc 192.168.0.200 20000
# cat /dev/mtdblock1 | nc 192.168.0.200 20000
# cat /dev/mtdblock2 | nc 192.168.0.200 20000
# cat /dev/mtdblock3 | nc 192.168.0.200 20000
# cat /dev/mtdblock4 | nc 192.168.0.200 20000

This stores the five NAND partitions in files named mtdblock*. Knowing the partition layout (u-boot "mtdparts" command or Linux dmesg) you can restore the whole flash with it.

Setting date and time

To set the date and time you need to open a terminal or ssh to the device. To set the date and time to August 9 19:02 2007 type:

# date -s 080919022007

The screensaver might turn on as you execute this command - just tap the screen to get back.

Now, you need to synchronize the time with the hardware date/time by typing:

# hwclock --systohc

Where to from here

You'll probably want to play with some of the interesting hardware in this device. Obviously, you can explore the applications available through the touch-screen interface. But for those who prefer doing things more in the raw from a shell prompt, you can manually use GSM, manually use SMS, or you can start playing with the GPS.