GitBook: [master] 324 pages modified

gettingstarted/programming/README.md

@@ -0,0 +1,16 @@
+# Programming the modules
+
+Now that you have connected and updated your pycom module and installed all the required software on your computer, we can begin programming your Pycom module.
+
+If this is your first time using a Pycom module we highly recommend you read through the following pages:
+
+* [**Introduction to MicroPython:**](micropython.md) This page will explain what Micropython is and its relation to Python.
+* [**MicroPython Examples:**](examples.md) We also recommend you browse these short MicroPython examples to familiarise yourself with its syntax. This is not meant as a comprehensive guide to MicroPython programming but rather a reference to those who already know programming. If you are new to python, or programming all together, we highly recommend searching the internet for Python tutorials. There are many very good tutorials available for free and the skills you learn will be easily transferable to our platform.
+* [**Your first Pymakr project:**](first-project.md) Once you understand what MicroPython is, this guide will take you through setting up your first Pymakr project to blink the on-board RGB LED. This guide will explain the structure of a MicroPython project as well as how to upload it to your module.
+
+Once you are familiar with MicroPython and Pymakr, the recommended way of uploading code to your module, you can explore the pages below. These will discuss in greater detail the various mechanisms for running code on your device as well as how to recover it if something goes wrong.
+
+* [**REPL:**](repl/) The REPL \(Read Evaluate Print Loop\) is an interactive terminal that allows you to type in and test your code directly on the device, just like interactive python interpreter. It can be accessed via [UART](repl/serial.md) or [Telnet](repl/telnet.md). This is accessed easiest by using Pymakr but if you wish to use other tools, this page will explain how.
+* [**FTP:**](ftp.md) All Pycom modules start up with a WiFi access point enabled, and a simple FTP server running on it. Once connected to the WiFi network, you can use FTP to transfer files over to your device wirelessly. This can be very useful if you do not have physical access to your device.
+* [**Safe Boot:**](safeboot.md) It is possible that some code you upload to your module will prevent you accessing the REPL or FTP server, preventing you from updating your scripts. This guide will detail how to safe boot your module and how to remove the offending scripts from it.
+

gettingstarted/programming/examples.md

@@ -0,0 +1,108 @@
+# MicroPython Examples
+
+To get you started with Python \(MicroPython\) syntax, we've provided you with a number of code examples.
+
+## Variable Assignment
+
+As with Python 3.5, variables can be assigned to and referenced. Below is an example of setting a variable equal to a string and then printing it to the console.
+
+```python
+variable = "Hello World"
+print(variable)
+```
+
+## Conditional Statements
+
+Conditional statements allow control over which elements of code run depending on specific cases. The example below shows how a temperature sensor might be implemented in code.
+
+```python
+temperature = 15
+target = 10
+if temperature > target:
+    print("Too High!")
+elif temperature < target:
+    print("Too Low!")
+else:
+    print("Just right!")
+```
+
+## Loops \(For & While loop\)
+
+Loops are another important feature of any programming language. This allows you to cycle your code and repeat functions/assignments/etc.
+
+`for` loops allow you to control how many times a block of code runs for within a range.
+
+```python
+x = 0
+for y in range(0, 9):
+    x += 1
+print(x)
+```
+
+`while` loops are similar to `for` loops, however they allow you to run a loop until a specific conditional is `true/false`. In this case, the loop checks if `x` is less than `9` each time the loop passes.
+
+```python
+x = 0
+while x < 9:
+    x += 1
+print(x)
+```
+
+## Functions
+
+Functions are blocks of code that are referred to by name. Data can be passed into it to be operated on \(i.e. the parameters\) and can optionally return data \(the return value\). All data that is passed to a function is explicitly passed.
+
+The function below takes two numbers and adds them together, outputting the result.
+
+```python
+def add(number1, number2):
+    return number1 + number2
+
+add(1, 2) # expect a result of 3
+```
+
+The next function takes an input name and returns a string containing a welcome phrase.
+
+```python
+def welcome(name):
+    welcome_phrase = "Hello, " + name + "!"
+    print(welcome_phrase)
+
+welcome("Alex") # expect "Hello, Alex!"
+```
+
+## Data Structures
+
+Python has a number of different data structures for storing and manipulating variables. The main difference \(regarding data structures\) between C and Python is that Python manages memory for you. This means there’s no need to declare the sizes of lists, dictionaries, strings, etc.
+
+### Lists
+
+A data structure that holds an ordered collection \(sequence\) of items.
+
+```python
+networks = ['lora', 'sigfox', 'wifi', 'bluetooth', 'lte-m']
+print(networks[2]) # expect 'wifi'
+```
+
+### Dictionaries
+
+A dictionary is like an address-book where you can find the address or contact details of a person by knowing only his/her name, i.e. keys \(names\) are associate with values \(details\).
+
+```python
+address_book = {'Alex':'2604 Crosswind Drive','Joe':'1301 Hillview Drive','Chris':'3236 Goldleaf Lane'}
+print(address_book['Alex']) # expect '2604 Crosswind Drive'
+```
+
+### Tuple
+
+Similar to lists but are immutable, i.e. you cannot modify tuples after instantiation.
+
+```python
+pycom_devices = ('wipy', 'lopy', 'sipy', 'gpy', 'fipy')
+print(pycom_devices[0]) # expect 'wipy'
+```
+
+{% hint style="info" %}
+For more Python examples, check out these [tutorials](https://www.tutorialspoint.com/python3/). Be aware of the implementation differences between MicroPython and Python 3.5.
+{% endhint %}
+

gettingstarted/programming/first-project.md

@@ -0,0 +1,113 @@
+# Your first Pymakr project
+
+This guide will take you through how to setup your first project with Pymakr and make the on-board RGB LED flash various colours.
+
+## Creating a project in Pymakr
+
+1. Firstly you will need to create a new, empty, directory on your computer.
+
+   For this example we will create one called `RGB-Blink`.
+
+2. Next you will need to open either Atom or Visual Studio Code depending on
+
+   which you setup previously.
+
+3. Once the text editor has loaded you will need to click `File` > `Open`, and open the directory you created in step 1
+
+{% hint style="info" %}
+If you are using Atom, it is important to check at this point that Atom has successfully identified the project. The name of the directory you created in step 1 \(`RGB-Blink` in this case\) should be shown in the Pymakr pane like so:
+
+![](../../.gitbook/assets/atom_project.png)
+
+If this is not the case you can press `alt-ctrl-r` on Windows/Linux or `ctrl-alt-cmd-l` on macOS, in order to reload Atom and fix the issue.
+{% endhint %}
+
+4. Now that you have a project created, we need to add some files to it. A standard MicroPython project has the following structure:
+
+```text
+RGB-Blink
+|-lib
+|  |- some_library.py
+|-boot.py
+|-main.py
+```
+
+* `boot.py` This is the first script that runs on your module when it
+
+  turns on. This is often used to connect a module a a WiFi network so that
+
+  Telnet and FTP can be used without connecting to the WiFi AP created by the
+
+  module and not cluttering up the `main.py` file. As a beginner you do not
+
+  need to use a `boot.py`.
+
+* `main.py` This script runs directly after `boot.py` and should contain
+
+  the main code you wish to run on your device.
+
+* `lib` It is often a good idea to split out re-usable code into libraries.
+
+  If you want to create or use libraries created by others, you will need to
+
+  create a `lib` directory and put the library files in this. It is important
+
+  that you put `.py` files directly into `lib` rather than creating a directory
+
+  tree. By default MicroPython will not detect any libraries within
+
+  sub-directories.
+
+For this example, you will just need to create a `main.py` file.
+
+Now that the project structure is setup, you may wish to configure project specific settings for Pymakr e.g. Which serial port to use. On Atom you need to click the `^` button on the Pymakr pane, then click `Project Settings`. On Visual Studio Code you need to click the `All commands` button on the bottom of the windows, then click `Pymakr > Project Settings`. This creates a file called `pymakr.conf` inside your project and populates it with default settings copied over from your global settings. A detailed explanation of these settings can be found [here](../../pymakr/settings.md).
+
+## Controlling the on-board LED
+
+Now that you have setup and configured your project, we can move on to programming your module. The first thing we will need to do is import some libraries in order to interact with the on-board LED. The Pycom firmware comes with a large amount of libraries for standard functionality built-in. You can find out more about these in the [API documentation](../../firmwareapi/introduction.md). For this example you will need to open the `main.py` file and add the following code:
+
+```python
+import pycom
+import time
+```
+
+This will import two libraries, `Pycom` which is responsible for Pycom specific features, such as the on-board LED and `time` which is a standard library used timing and delays.
+
+You may have noticed that when you power up your Pycom module, the on-board LED blinks blue on a regular basis. This "heartbeat" is used as a way of know that your module has powered up and started correctly. Before we can change the colour of this LED we need to disable this heart beat. Below your imports you will need to add the following:
+
+```python
+pycom.heartbeat(False)
+```
+
+Now it's time to test your code. On the Pymakr pane/bottom of the window you will see a `run` button. \(If you haven't connected to your device yet, you will need to do that first\). When you click the run button, the code in the currently open file will be executed on the device, but it won't copy it to the device. After running this code, you should see that that on-board LED stops blinking blue.
+
+Now that we can confirm the device is connected and Pymakr is able to run code on it, we can complete our script to blink the LED like so:
+
+```python
+import pycom
+import time
+
+pycom.heartbeat(False)
+
+while True:
+    pycom.rgbled(0xFF0000)  # Red
+    time.sleep(1)
+    pycom.rgbled(0x00FF00)  # Green
+    time.sleep(1)
+    pycom.rgbled(0x0000FF)  # Blue
+    time.sleep(1)
+```
+
+Once you run the above script, it will run forever. You will notice this prevents you from accessing the interactive REPL on the device \(You cannot see the `>>>` prompt\). In order to stop the script, click onto the Pymakr terminal, and press `ctrl-c` on your keyboard. This should stop the script running and return you to the interactive REPL.
+
+## Uploading to your module
+
+In the previous section we got code running on on your Pycom module using the `run` feature of Pymakr. This is useful for quick testing but has a couple of drawbacks. Firstly the code does not remain on the device permanently. If you reboot the device, it will no longer be running your code. Secondly, it will only work if you are using libraries built into the firmware. If you need any extra libraries, these need to be copied to the device first. This is where the `upload` feature comes in. If instead of `run` you click `upload`, Pymakr will upload all the files in the project \(so long as their type is in the `sync_file_types` setting for your project\). These then persist on your device even between reboots, and allows you to use libraries from the `lib` folder in your project.
+
+If you need to remove files from your device you have two options, either connect via FTP and manage your files that way or format the device's internal flash like so:
+
+```python
+import os
+os.mkfs('/flash')
+```
+

gettingstarted/programming/ftp.md

@@ -0,0 +1,41 @@
+# FTP
+
+There is a small internal file system accessible with each Pycom device, called `/flash`. This is stored within the external serial flash memory. If a microSD card is also connected and mounted, it will be available as well. When the device starts up, it will always boot from the `boot.py` located in the `/flash` file system.
+
+The file system is accessible via the native FTP server running on each Pycom device. Open an FTP client and connect to:
+
+* url: `ftp://192.168.4.1`
+* username: `micro`
+* password: `python`
+
+See [network.server](../../firmwareapi/pycom/network/server.md) for information on how to change the defaults. The recommended clients are:
+
+* macOS/Linux: default FTP client
+* Windows: Filezilla and FireFTP
+
+For example, from a macOS/Linux terminal:
+
+```bash
+$ ftp 192.168.4.1
+```
+
+The FTP server doesn’t support active mode, only passive mode. Therefore, if using the native unix FTP client, immediately after logging in, run the following command:
+
+```bash
+ftp> passive
+```
+
+The FTP server only supports one connection at a time. If using other FTP clients, please check their documentation for how to limit the maximum allowed connections to one at a time.
+
+## FileZilla
+
+If using FileZilla, it's important to configure the settings correctly.
+
+Do not use the quick connect button. Instead, open the site manager and create a new configuration. Within the `General` tab, ensure that encryption is set to: `Only use plain FTP (insecure)`.
+
+![](../../.gitbook/assets/filezilla-settings-1.png)
+
+In the `Transfer Settings` tab, limit the max number of connections to one. Other FTP clients may behave in a similar ways; visit their documentation for more specific information.
+
+![](../../.gitbook/assets/filezilla-settings-2.png)
+

gettingstarted/programming/micropython.md

@@ -0,0 +1,26 @@
+# Introduction to MicroPython
+
+Our boards work with [MicroPython](https://micropython.org/); a Python 3.5 implementation that is optimised to run on micro controllers. This allows for much faster and more simple development process than using C.
+
+![](../../.gitbook/assets/micropython%20%281%29.jpg)
+
+## Booting into MicroPython
+
+When booting, two files are executed automatically: first `boot.py` and then `main.py`. These are placed in the `/flash` folder on the board. Any other files or libraries can be placed here as well, and can be included or used from `boot.py` or `main.py`.
+
+The folder structure in `/flash` looks like the picture below. The files can be managed either using FTP or using the Pymakr Plugin.
+
+![](../../.gitbook/assets/mp-filestructure%20%281%29.png)
+
+## Tips & Tricks
+
+Micropython shares majority of the same syntax as Python 3.5. The intention of this design is to provide compatibility upwards from Micropython to Python 3.5, meaning that code written for Micropython should work in a similar manner in Python 3.5. There are some minor variations and these should taken viewed as implementation differences.
+
+Micropython also has a number of Micropython specific libraries for accessing hardware level features. Specifics relating to those libraries can be found in the Firmware API Reference section of this documentation.
+
+{% hint style="info" %}
+Micropython, unlike C/C++ or Arduino, **does not use braces {} to indicate blocks of code** specified for class and function definitions or flow control. Blocks of code are denoted by line indentation, which is strictly enforced.
+
+The number of spaces in the indentation is variable but all statements within a block must be indented the same amount.
+{% endhint %}
+

gettingstarted/programming/repl/README.md

@@ -0,0 +1,24 @@
+# REPL
+
+REPL stands for Read Evaluate Print Loop, and is the name given to the interactive MicroPython prompt that is accessible on the Pycom devices. Using the REPL is by far the easiest way to test out Python code and run commands. You can use the REPL in addition to writing scripts in `main.py`.
+
+The following pages will explain how to use the REPL with both Serial USB and Telnet connections.
+
+The REPL includes the following features:
+
+* Input history: use arrow up and arrow down to scroll through the history
+* Tab completion: press tab to auto-complete variables or module names
+* Halt any executing code: with `Ctrl-C`
+* Copy/paste code or output: `Ctrl-C` and `Ctrl-V`
+
+{% hint style="info" %}
+There are a number of useful shortcuts for interacting with the MicroPython REPL. See below for the key combinations;
+
+* `Ctrl-A` on a blank line will enter raw REPL mode. This is similar to permanent paste mode, except that characters are not echoed back.
+* `Ctrl-B` on a blank like goes to normal REPL mode.
+* `Ctrl-C` cancels any input, or interrupts the currently running code.
+* `Ctrl-D` on a blank line will do a soft reset.
+* `Ctrl-E` enters ‘paste mode’ that allows you to copy and paste chunks of text. Exit this mode using `Ctrl-D`.
+* `Ctrl-F` performs a "safe-boot" of the device that prevents `boot.py` and `main.py` from executing
+{% endhint %}
+

gettingstarted/programming/repl/serial.md

@@ -0,0 +1,54 @@
+# Serial USB \(UART\)
+
+To use the REPL, a Pycom device must be connected to the host computer with a USB connection either to an Expansion Board or to serial converter \(a diagram of how to do this can be found the the [getting started](../../introduction.md) page for your module\).
+
+In order to connect to the REPL over USB serial, there are multiple methods. Detailed below are the explanations of how to do it in MacOS, Linux and Windows.
+
+## All platforms
+
+By far the easiest way to access the USB UART REPL is via the our [Pymakr plug-in](../../../pymakr/installation/) for Atom and Visual Studio Code. This adds a pane to the bottom of the editors that allows you to directly access the REPL and any output from the device. Detailed instructions on how to setup Pymakr can be found [here](../../../pymakr/installation/).
+
+## macOS and Linux
+
+To open a serial USB connection from macOS, any serial tool may be used; in this example, the terminal tool `screen` will be used.
+
+Open a terminal instance and run the following commands:
+
+```bash
+$ screen /dev/tty.usbmodem* 115200
+```
+
+Upon exiting `screen`, press `CTRL-A CTRL-\`. If the keyboard does not support the `\`-key \(i.e. an obscure combination for `\` like `ALT-SHIFT-7` is required\), the key combination can be remapped for the `quit` command:
+
+* create `~/.screenrc`
+* add bind `q` to the `exit` command
+
+This will allow screen to exited by pressing `CTRL-A Q`.
+
+{% hint style="info" %}
+On Linux, `picocom` or `minicom` may be used instead of `screen`. The usb serial address might also be listed as `/dev/ttyUSB01` or a higher increment for `ttyUSB`. Additionally, the elevated permissions to access the device \(e.g. group uucp/dialout or use `sudo`\) may be required.
+{% endhint %}
+
+## Windows
+
+A terminal emulator is needed to open the connection from Windows; the easiest option is to download the free program, [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html).
+
+### COM Port
+
+To use PuTTY the serial port \(COM port\) in which the Pycom device is connected, must be located. In Windows, this information can be found from the 'Device Manager' program.
+
+1. Open the Windows start menu and search for 'Device Manager'
+2. The COM port for the Pycom device will be listed as 'USB Serial Device' or a similar name
+3. Copy/Write down the associated COM port \(e.g. `COM4`\)
+
+### Using Putty
+
+1. With PuTTY open, click on `Session` in the left-hand panel
+2. Next click the `Serial` radio button on the right and enter the associated
+
+   COM port \(e.g. `COM4`\) in the `Serial Line` box
+
+3. Finally, click the `Open` button
+
+![](../../../.gitbook/assets/putty.png)
+

gettingstarted/programming/repl/telnet.md

@@ -0,0 +1,41 @@
+# Telnet REPL
+
+Pycom devices also support a connection via `telnet`, using the device's on board WiFi/WLAN. Connect to the device's WiFi Access Point \(AP\) and using the following credentials to connect to the AP. The WiFi `SSID` will appear upon powering on a Pycom Device for the first time \(e.g. `lopy-`\). To re-enable this feature at a later date, please see [network.WLAN](../../../firmwareapi/pycom/network/wlan.md).
+
+* password: `www.pycom.io`
+
+## Telnet Server
+
+Additionally, to use the MircoPython REPL over telnet, further authentication is required. The default credentials for the telnet server are:
+
+* username: `micro`
+* password: `python`
+
+See [network.server](../../../firmwareapi/pycom/network/server.md) for info on how to change the default authentication.
+
+## All platforms
+
+By far the easiest way to access the Telnet REPL is via the our [Pymakr plug-in](../../../pymakr/installation/) for Atom and Visual Studio Code. This adds a pane to the bottom of the editors that allows you to directly access the REPL and any output from the device. Detailed instructions on how to setup Pymakr can be found [here](../../../pymakr/installation/).
+
+## macOS and Linux
+
+Once the host machine is connected to the Pycom device's Access Point, a telnet connection may be opened from a terminal instance.
+
+```bash
+$ telnet 192.168.4.1
+```
+
+Upon connection, the telnet program will prompt for the `username` and `password` in the section above.
+
+## Windows
+
+A terminal emulator is needed to open a telnet connection from Windows; the easiest option is to download the free program, [PuTTY](http://www.putty.org/).
+
+1. With PuTTY open, select telnet as connection type and leave the default port \(`23`\)
+2. Next enter the IP address of the Pycom device \(e.g. `192.168.4.1`\)
+3. Finally click `Open`
+
+{% hint style="info" %}
+When using a Pycom device with a personal, home or office WiFi access point, the telnet connection may still be used. In this instance, the user will need to determine the Pycom device's local IP address and substitute this for `192.168.4.1`, referred to in the earlier sections.
+{% endhint %}
+

gettingstarted/programming/safeboot.md

@@ -0,0 +1,53 @@
+# Safe boot
+
+If powering up normally or upon pressing the reset button, a Pycom module will boot into standard mode; the `boot.py` file will be executed first, followed by `main.py`. It is possible to alter the boot procedure of the module by tying certain pins `high` or `low` when the module boots.
+
+## Bootloader
+
+If you updated your device before using it, you have already put the device into bootloader mode. This is achieved by connecting `G23` to `GND` while the device boots. If you used a Pysense/Pytrack to update, it did this automatically for you. You only need to put your Pycom module into bootloader mode if you are updating its firmware, or are programming your own low level code. This is not required if you are updating your MicroPython code.
+
+## Safe Boot
+
+Some times the code you have written will prevent you gaining access to the REPL or prevent you updating your code. Some example may be:
+
+* You disabled the WiFi/UART
+* Your code gets stuck before reaching the REPL
+* You set a socket as blocking but never receive any data
+
+In order to fix this you can safe boot your module. This will prevent `boot.py` and `main.py` from being executed and will drop you straight into the interactive REPL. After reset, if `P12` pin is held `high` \(i.e. connect it to the `3V3` output pin\), the heartbeat LED will begin flashing orange slowly. If after 3 seconds the pin is still held high, the LED will start blinking faster. In this mode the module will do the same as previously explained but it will also select the previous OTA image to boot if you have updated the module via the OTA update procedure \(updates performed via the firmware update tool do not count\). This is useful if you flashed a OTA update that breaks the device.
+
+Pin `P12` released during:
+
+| 1st 3 secs window | 2nd 3 secs window |
+| :--- | :--- |
+| Disable `boot.py` and `main.py` | Same as previous but using previous OTA firmware |
+
+The selection made during safe boot is not persistent, therefore after the next normal reset, the latest firmware will proceed to run again.
+
+If problems occur within the filesystem or you wish to factory reset your module to remove your code, run following code in the REPL:
+
+```python
+>>> import os
+>>> os.mkfs('/flash')
+```
+
+{% hint style="danger" %}
+Be aware, resetting the flash filesystem will delete all files inside the internal device storage \(not the SD card\) and they cannot be recovered.
+{% endhint %}
+
+## Reset
+
+Pycom devices support both soft and hard resets. A soft reset clears the state of the MicroPython virtual machine but leaves hardware peripherals unaffected. To do a soft reset, press `Ctrl+D` on the REPL or from within a script, run:
+
+```python
+>>> import sys
+>>> sys.exit()
+```
+
+A hard reset is the same as performing a power cycle to the device. In order to hard reset the device, press the `reset` switch or run:
+
+```python
+>>> import machine
+>>> machine.reset()
+```
+