Modifying boot.py

There is a small file system in the flash memory on the WiPy. This contains all the support code, the files run at boot time, and any code the user uploads to the board (unless you use an SD card, which I highly recommend).

The boot sequence when you power on or reset the board is

  1. Power on
  2. Bring up the Python interpreter (REPL)
  3. Execute the boot.py program
  4. Execute the main.py program
  5. Start the telnet and ftp servers

If you want to change the network or server configurations (like the username and password), you edit the boot.py program.

To edit the boot.py program, you first need to get it from the WiPy board. You do this using the ftp program (ftp stands for File Transfer Protocol).

  • When you connect using ftp, you will be prompted for a login and password.
  • The default login is micro and the default password is python
  • After you have connected, you need to enter the passive mode and the binary mode. Type passive and  press Enter. Then type bin and press Enter.
  • Then change to the /flash subdirectory by typing cd /flash and pressing Enter.
  • Then just type get boot.py to copy the boot.py template to your local computer.

Then edit your local copy of boot.py using your favorite editor.

If you make a mistake in boot.py or main.py you will likely brick the device. This guide has instructions for fixing it.

Here is my boot.py program. You will need to change the configuration to match your local network. Note that this assumes yu are assigning a static IP address to the device! I also assume you have a micro-SD card (FAT formatted) in the SD card slot. You really want an SD card for extra storage!

On UNIX systems (Linux and Mac OS X) and Windows you can find appropriate network configurations by using the netstat command. Open a terminal or the command prompt and enter netstat -rn

You want to take the gateway address from the 0.0.0.0 destination, so in this case, the gateway would be 192.168.0.1. Take the netmask value from your local wireless network; in this case, that is 192.168.0.0, so the appropriate netmask is 255.255.255.0. The DNS server is usually the IP address of your wireless access point (in this case, 192.168.0.1) but if you don't know it or aren't sure, 8.8.8.8 is always a safe bet - that's Google's open DNS server.

The only other thing yo need to do is find an open IP address to use on your local network. I keep a list of all used IP addresses in my network's /etc/hosts file. Another way to find an open IP address is to log into your wireless access point and look for all the assigned DHCP addresses and pick one that's "far" away from any assigned addresses. On my network, I have everything between .2 and .100 assigned to various devices, like my huge 158-core cluster. DHCP assigns dynamic addresses between .100 and .150, so I picked .200 for my WiPy. Remember that .254 is the maximum value for any address component (called an "octet").

Note: it is possible to use DHCP to get an address, but the WiPy board will not register with DNS for a .local address. To get to the board you have to use some method to find out the IP address or use a fairly complex method to enable the REPL on the UART interface and connect to the board over USB (which is beyond the scope of this intro guide).

Download: file
# boot.py -- run on boot-up
# can run arbitrary Python, but best to keep it minimal
#
import network
import machine
from machine import SD
from network import WLAN
import os
import time
#
# Set up WLAN
#
wlan = WLAN() # get current object, without changing the mode

ssid     = 'YOUR_SSID'
password = 'YOUR_WIFI_PASSWORD'
ip       = 'YOUR_STATIC_IP_ADDRESS'
net_mask = 'YOUR_NETMASK'
gateway  = 'YOUR_GATEWAY_IP_ADDRESS'
dns      = 'YOUR_DNS_SERVER'

def init():
    wlan.init(WLAN.STA)
    wlan.ifconfig(config=(ip, net_mask, gateway, dns))

def connect():
    wlan.connect(ssid, auth=(WLAN.WPA2, password), timeout=5000)
    while not wlan.isconnected():
        machine.idle() # save power while waiting
    cfg = wlan.ifconfig()
    print('WLAN connected ip {} gateway {}'.format(cfg[0], cfg[2]))

def set():
    init()
    if not wlan.isconnected():
        connect()

set()

#
# Set up server
#
server = network.Server()
server.deinit()
server.init(login=('YOUR_USERNAME','YOUR_PASSWORD'),timeout=600)
#
# SD card support
#
sd = SD()
os.mount(sd, '/sd')
The WiPy does not support SSH, SFTP, or HTTPS! This means that any connections to the device will send your login and password in cleartext. Use a disposable password!

Once you have modified boot.py to match your local network configuration, use ftp to put the program in the /flash directory on the WiPy.. The server only supports passive mode connections. Also, the binary mode file transfer should be used when transferring files. Here is a screenshot that illustrates the connection:

The commands you need to enter after you've made an ftp connection are:

  • login
  • password
  • passive
  • bin
  • cd /flash
  • put boot.py
  • quit

Once you have uploaded the new boot.py program, press the reset button on the WiPy to execute the new configuration program. Your WiPi should now be on your local network and accessible with the login and password you set. Try telnet to the IP address you assigned and log in with the credentials you specified. You should then be back at the REPL prompt. 

If you can't connect and (likely) don't see the flashing heartbeat LED on the WiPy, you may have made a mistake editing the boot.py program. See the page titled How To Recover Your Bricked WiPy for instructions on how to get back into the device.

This guide was first published on Aug 31, 2016. It was last updated on Aug 31, 2016. This page (Modifying boot.py) was last updated on Nov 13, 2019.