Add LICENSE and README

LICENSE

@@ -0,0 +1,11 @@
+Copyright 2022 Brian Starkey <stark3y@gmail.com>
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,128 @@
+# `picowota` - Raspberry Pi Pico W OTA bootloader
+
+> `picowota`, kinda sounds like you're speaking [Belter](https://expanse.fandom.com/wiki/Belter)
+
+This project implements a bootloader for the Raspberry Pi Pico W which allows
+upload of program code over WiFi ("Over The Air").
+
+The easiest way to use it is to include this repository as a submodule in the
+application which you want to be able to update over WiFi.
+
+There's an example project using picowota at https://github.com/usedbytes/picowota_blink
+
+## Using in your project
+
+First add `picowota` as a submodule to your project:
+```
+git submodule add https://github.com/usedbytes/picowota
+git submodule update --init picowota
+git commit -m "Add picowota submodule"
+```
+
+Then modifiy your project's CMakeLists.txt to include the `picowota` directory:
+
+```
+add_subdirectory(picowota)
+```
+
+`picowota` (currently) connects to an existing WiFi network, so you need to
+set the SSID and password for the network to connect to.
+
+You can either export the `PICOWOTA_WIFI_SSID` and `PICOWOTA_WIFI_PASS`
+environment variables, or set the CMake variables with the same name:
+
+```
+set(PICOWOTA_WIFI_SSID MyNetworkName)
+set(PICOWOTA_WIFI_PASS MyPassw0rd)
+```
+
+Then, you can either build just your standalone app binary (suitable for
+updating via `picowota` when it's already on the Pico), or a combined binary
+which contains the bootloader and the app (suitable for flashing the first
+time): 
+
+```
+picowota_build_standalone(my_executable_name)
+picowota_build_combined(my_executable_name)
+```
+
+Note: The combined target will also build the standalone binary.
+
+To be able to update your app, you must provide a way to return to the
+bootloader. By default, if GPIO15 is pulled low at boot time, then `picowota`
+will stay in bootloader mode, ready to receive new app code.
+
+You can also return to the bootloader from your app code - for example when a
+button is pressed, or in response to some network request. The
+`picowota_reboot` library provides a `picowota_reboot(bool to_bootloader)`
+function, which your app can call to get back in to the bootloader.
+
+```
+CMakeLists.txt:
+
+target_link_libraries(my_executable_name picowota_reboot)
+
+your_c_code.c:
+
+#include "picowota/reboot.h"
+
+...
+
+{
+
+	...
+
+	if (should_reboot_to_bootloader) {
+		picowota_reboot(true);
+	}
+
+	...
+
+}
+```
+
+## Uploading code via `picowota`
+
+Once you've got the `picowota` bootloader installed on your Pico, you can use
+the https://github.com/usedbytes/serial-flash tool to upload code to it.
+
+As long as the Pico is "in" the `picowota` bootloader (i.e. because there's no
+valid app code uploaded yet, or your app called `picowota_reboot(true);`), you
+can upload an app `.elf` file which was built by `picowota_build_standalone()`:
+
+(Assuming your Pico's IP address is 192.168.1.123):
+```
+serial-flash tcp:192.168.1.123:4242 my_executable_name.elf
+```
+
+After uploading the code, if successful, the Pico will jump to the newly
+uploaded app.
+
+## How it works
+
+This is derived from my Pico non-W bootloader, https://github.com/usedbytes/rp2040-serial-bootloader, which I wrote about in a blog post: https://blog.usedbytes.com/2021/12/pico-serial-bootloader/
+
+The bootloader code attempts to avoid "bricking" by storing a CRC of the app
+code which gets uploaded. If the CRC doesn't match, then the app won't get run
+and the Pico will stay in `picowota` bootloader mode. This should make it fairly
+robust against errors in transfers etc.
+
+## Known issues
+
+### Bootloader/app size and `cyw43` firmware
+
+The WiFi chip on a Pico W needs firmware, which gets built in to any program
+you build with the Pico SDK. This is relatively large - 300-400 kB, which is why
+this bootloader is so large.
+
+This gets duplicated in the `picowota` bootloader binary and _also_ the app
+binary, which obviously uses up a significant chunk of the Pico's 2 MB flash.
+
+It would be nice to be able to avoid this duplication, but the Pico SDK
+libraries don't give a mechanism to do so.
+
+### Expose and access point, rather than connecting to one
+
+It would perhaps be better if the bootloader set up an access point, rather than
+trying to connect to an existing network - or even better, provide the option.
+I expect that wouldn't be too hard to do.