Forth Lesson 23

Random Recipes

This is a collection of "How to Do X" snippets. Feel free to add your favorites.

Forcing EC Code Update on XO-1.75

On XO-1.75, the Embedded Controller code is executed from FLASH internal to the EC (on previous XOs, the EC code was executed from the same SPI FLASH chip that contained the Open Firmware code). The OFW SPI FLASH contains a copy of the EC code, and if that copy is newer than the running EC code, OFW auto-updates the EC code by writing the new copy into the internal EC FLASH.

There are circumstances where the auto-update doesn't work the way you want it; for example you might have a test version that doesn't register as "newer" than the running version. Or you might want to force a reversion to an older version.

To explicitly perform the EC FLASH update:

  ok flash-ec rom:ecimage.bin

For safety, that command requires the presence of both battery and AC power. You can bypass that safety check with:

  ok flash-ec! rom:ecimage.bin

rom:ecimage.bin refers to the copy of the EC code that is stored inside the OFW SPI FLASH. More generally, "rom:" refers to a "filesystem" inside that SPI FLASH, containing numerous images that OFW needs from time to time.

The target of the flash-ec command can be any file that OFW can access. For example:

  ok flash-ec u:mynewec.bin                         \ From USB stick
  ok flash-ec http:\\192.168.200.200\ecimage3.bin   \ From the web

Wireless Network Access from Open Firmware

OFW contains a network stack that supports numerous protocols including HTTP, Telnet, SMB (Windows File Sharing), TFTP, and NFS. On the XO, the network connection can be either the built-in wireless LAN or a plug-in USB Ethernet adapter. If a plug-in Ethernet adapter is present, it is used as the default network device, otherwise the wireless LAN is used.

Connecting to the Wireless LAN

You can list the wireless access points within range with:

  ok test /wlan
  RSSI: 49 SSID: OLPCOFW  Channel: 1
  RSSI: 49 SSID: 5247 1201  Channel: 1
  RSSI: 85 SSID: 09FX07016302  Channel: 6

By default, when you try to use the wireless LAN, OFW-on-XO tries to associate with an open access point named "OLPCOFW". If you want to perform wireless operations on a lot of XOs, you can set up such an access point to streamline subsequent operations.

You can manually change the association by specifying the ESSID of a different access point with:

  ok essid 09FX07016302

Dealing with access points that require authentication is more difficult, due to the variety of different authentication methods and password formats in the WiFi world; at the time of this writing, OFW does not support all the possibilities. One possibility that is does support is the old "WEP" form, which is rarely used these days:

  ok wep 00224488aa                   \ 40-bit/5-byte hex key format
  ok wep 00112233445566778899aabbcc   \ 128-bit/13-byte hex format
  ok " MyPwd" $wep                    \ 5-byte ASCII format
  ok " MyPassword123" $wep            \ 13-byte ASCII format

WPA is problematic at the moment - while OFW ostensibly supports WPA, OFW's facilities for converting WPA passphrases to the internal "Pairwise Master Key" representation are weak, bordering on unusable.

After you have entered the ESSID and optionally the authentication information, OFW network commands will automatically associate with the access point as needed.

Connecting to any Wireless LAN

Sometimes it might not be possible to know the ESSID in advance, yet you know it starts with a certain word. This happens in schools. The following code fragment can be used where the only access points that match the prefix school are those that can be used.

: prefix$  " school"  ;

d# 34 buffer: an-ssid
: an-ssid0  ( -- )        0 an-ssid c!  ;
: an-ssid!  ( ssid$ -- )  d# 32 min  an-ssid pack drop  ;
: an-ssid@  ( -- ssid$ )  an-ssid count  ;

dev /supplicant
: capture-ssid  ( ssid$ -- )
   \ test for hidden access point, first byte of essid is zero
   over c@  if          ( ssid$ )
      2dup
      prefix$           ( ssid$ ssid$ prefix$ )
      rot drop comp     ( ssid$ comparison )
      0= if
         \ a match by prefix, capture the ssid for re-use
         2dup an-ssid!
      then
   then                 ( ssid$ )
   type                 ( )
;
patch capture-ssid type .ie-short
dend

scan-wifi an-ssid@ $essid

The code works by intercepting the scan results, testing each name, and when it matches storing the name for later use. Then the latest stored name is used.

Some OFW Network Commands

The following network commands work on both wireless and wired (via a USB Ethernet adapter) networks.

  ok ping 192.168.200.1
  Scan for: OLPCOFW found
  Associate with: OLPCOFW
  DHCP got 192.168.200.22
  4 ms

If your DHCP server reports the name server address, OFW can use it to resolve hostnames:

  ok ping dev.laptop.org
  Associate with: OLPCOFW
  112 ms

The "Scan for:" and "DHCP got" messages are only shown once; OFW caches the information after the first time, so subsequent operations are faster.

  ok more http:\\firmworks.com\index.htm
  (displays some HTML as ASCII)

The more command is not network-specific; it will display any file. This illustrates the fact that any OFW file-oriented command can apply to a network file by using the "http:\\SERVER\FILE" syntax. Note the use of backslashes (\) instead of forward slashes (/). This is an unfortunate consequence of OFWs use of forward slash to separate pathname components in the device tree.

  ok fload smb:\\USER:PASSWORD@SERVER\path\to\file.fth

The above shows an example of loading a Forth source code file from a Windows share (SMB server). You can also say "cifs" instead of "smb" - CIFS (Common Internet File System) and SMB (Server Message Block) are different names for the same thing.

OFW speaks NFS (Network File System) too:

  ok fload nfs:\\SERVER\path\to\file.fth

You can use TELNET to talk to OFW from another machine:

  ok telnetd
  Associate with: OLPCOFW
  my-args = last
  Initial configuration: Using the previous configuration
  telnet://192.168.200.22

Now run a telnet program on another machine to connect to OFW on the XO.

  $ telnet 192.168.200.22
  Trying 192.168.200.22...
  Connected to 192.168.200.22.
  Escape character is '^]'
  ok here .
  fdae68dc
  ^]
  telnet> quit
  Connection closed

You can update OFW via the network:

  ok flash http:\\dev.laptop.org\pub\firmware\q4b09\q4b09.rom
  Reading http:\\dev.laptop.org\pub\firmware\q4b09\q4b09.rom
  Scan for: OLPCOFW found
  Associate with: OLPCOFW
  DHCP got 192.168.200.22
  Got firmware version: CL2   Q4B09  Q4B
  Checking integrity ...
  (etc)

Keeping the WLAN active

select ip

or

d# 1000 to #pings   ping 10.0.0.1

which pings an IP address 10.0.0.1 for 1000 cycles.

Without a DHCP server

If a wireless access point does not provide a DHCP server, or if you wish to avoid using one, OpenFirmware can be configured manually for an IP address. Exactly which address to use is up to you. Here's an example:

setenv ip-address 10.0.0.250
setenv ip-dns-server 8.8.8.8
setenv ip-netmask 255.255.255.0
setenv ip-router 10.0.0.84
setenv ip-domain mit.edu
essid AP
telnetd
Scan for: AP found
Associate with: AP
telnet://10.0.0.250