sascha_hemi/pycom-documentation
1
0
Fork 0
mirror of https://github.com/sascha-hemi/pycom-documentation.git synced 2026-03-21 08:06:34 +01:00
Code Issues Packages Projects Releases Wiki Activity

improved getting started guide

Browse Source 
suggestions by Peter
This commit is contained in:
gijsio
2020-07-27 14:01:38 +02:00
parent 7408868206
commit d1621915dc
2 changed files with 47 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
content/gettingstarted/_index.md
View File

@@ -22,71 +22,74 @@ In the following guide, we will explain the basic process to get started using y
# Step 1: Setting up the hardware
Congratulations on your Pycom module! In the first part of this getting started guide, we will take you through setting up your device. Firstly we will cover how to connect the module to your computer via USB.
In the first part of this getting started guide, we will take you through setting up your device. Firstly we will cover how to connect the module to your computer via USB.
#### Connect your board to your computer through USB
This step works the same for all our development boards and expansion boards. Insert your development board (Lopy, Wipy, etc.) into the expansion board (Pytrack, Pysense, etc.) with the reset button and RGB LED above the USB connector like shown below. Connect an USB cable to the USB port and your computer. Now, you can talk to your device through USB, but we still need some software to upload your first program!
This step works the same for all our development boards and expansion boards. Insert your development board (Lopy, Wipy, etc.) into the expansion board (Pytrack, Pysense, Expansion board etc.) with the reset button and RGB LED above the USB connector like shown below. Connect an USB cable to the USB port and your computer. Now, you can talk to your device through USB, but we still need some software to upload your first program!
![](/gitbook/assets/expansion_board_3_lopy4.png)
>Note: If you do not have an expansion board, you are able to use a [USB-Serial converter](/gettinstarted/programming/usbserial/) or [WiFi](/gettingstarted/programming/ftp/) to connect.
# Step 2: Setting up your computer
Now that your module is successfully connected, you will need to install some software on your computer to interface with it. For this, we use Pymakr, a plugin for both Visual Studio Code or Atom IDE. Through one of the environments, we can connect to the board and talk python! Follow the link below for the installation instructions:
Now that your module is successfully connected, you will need to install some software on your computer to interface with it. For this, we use Pymakr, a plugin for both Visual Studio Code and Atom IDE. Through either one of the environments, we can connect to the board and talk Python!
Follow the link below for the installation instructions:
- [Atom](/gettingstarted/software/atom/)
- [VS Code](/gettingstarted/software/vscode/)
Once you have installed and opened the IDE, the board should automatically show up in the terminal. If not, check if any of your other plugins are in conflict.
Once you have installed and opened the IDE, the board should automatically show up in the terminal. If not, check if any of your other plugins are in conflict. If everything is correct, the REPL (Read Evaluate Print Loop) terminal will show the classic Python `>>>`.
If everything is correct, the terminal will show `>>>`.
>Note: If your device does not get recognized the first time on Windows, check if you need [additional drivers](/gettingstarted/software/drivers/)
# Step 3: Programming your module
Now that you have a connected module and all the required software installed it is time to begin programming your device!
Now that you have connected your device and installed Pymakr, it is time to begin programming your device!
### Running your first code
If you have any experience with python, you know that the `>>>` means we can start typing commands! Type the following commands in the REPL terminal:
```python
>>> import pycom
>>> pycom.heartbeat(False)
>>> pycom.rgbled(0x330033)
```
This will turn the RGB LED on your device purple! Notice that the REPL does not give any feedback. Only when we make a mistake, or ask it to return something will it give us a response.
In this first example, we will make the on-board RGB LED flash different colors.
### Creating a project in Pymakr
In this first project, we will make the on-board RGB LED flash different colors.
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.
2. Open the project folder you have created in your IDE.
3. Once the text editor has loaded you will need to click `File` > `Open`, and open the directory you created in step 1
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.
4. Now that you have created a poject, we need to add some files. A standard MicroPython project will have a `lib` folder for additional libraries, and two python files: `main.py` and `boot.py`.
3. Now, we will need to add some files. A standard MicroPython project will have a `lib` folder for additional libraries, and two python files: `main.py` and `boot.py`.
* `main.py` This script runs directly after `boot.py` and should contain the main code you wish to run on your device.
* `boot.py` This is the first script that runs on your module when it turns on. This is often used to connect a module to a network without cluttering up the `main.py` file. As a beginner you generally do not need to use a `boot.py`.
* 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.
* 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. For example, the extra sensor libraries for the Pytrack, Pysense and Pyscan are put in this folder. In this example, we will not use it.
Your file structure should look something like this:
![]()
### Controlling the on-board RGB LED
#### Controlling the on-board RGB 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). For this example you will need to open the `main.py` file and add the following code:
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 built-in modules. You can find out more about these in the [API documentation](/firmwareapi/introduction). 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.
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 for 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:
>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
@@ -94,9 +97,9 @@ 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 it's time to test your code. On the Pymakr pane, you will see a `run` button, but als an `upload (to device)` button. For now, we will use `run`.
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:
After running the example code above, you should see that that on-board LED stops blinking blue. Now, we can complete our script to blink the LED like so:
```python
import pycom
@@ -114,24 +117,23 @@ while True:
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.
Once you run the above script, it will run forever (due to the infinite `While`-loop). In order to stop the script, click onto the Pymakr terminal, and press `ctrl-c` on your keyboard. This stops the script and returns to the interactive REPL.
Great work, the RGB-LED on your device should now blink in red, green and blue
### 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.
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. 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 can use the following commands:
```python
import os
os.fsformat('/flash')
>>> import os
>>> os.fsformat('/flash')
```
# Step 4: Further reading
Now that we got the basic example running, you can continue with the links below.
# Step 4: Further references
Now that we got the basic example running, you can proceed to develop your own application! For further references, you can check the links below:
* [More examples](/tutorials/)

36
content/gettingstarted/software/vscode.md
View File

@@ -8,27 +8,29 @@ aliases:
Pycom supports Microsoft's Visual Studio Code IDE platform with the Pymakr Plugin.
First [download and install Visual Studio Code](https://code.visualstudio.com/). You will also need NodeJS installed on your PC. Please download the latest LTS version available [from the NodeJS website.](https://nodejs.org/)
1. First [download and install Visual Studio Code](https://code.visualstudio.com/).
2. You will also need NodeJS installed on your PC. Please download the latest LTS version available [from the NodeJS website.](https://nodejs.org/)
Please follow these steps to install the [Pymakr VSCode Extension](https://marketplace.visualstudio.com/items?itemName=pycom.Pymakr):
1. Ensure that you have the latest VSCode installed and open.
3. Ensure that you have the latest VSCode installed and open.
![](/gitbook/assets/vsc_setup_step_1-1.png)
2. Navigate to the Extensions page, using the 5th button in the left navigation
4. Navigate to the Extensions page, using the 5th button in the left navigation
![](/gitbook/assets/vsc_setup_step_2-1.png)
3. Search for `Pymakr` and click the install button next to it.
5. Search for `Pymakr` and click the install button next to it.
![](/gitbook/assets/vsc_setup_step_3.png)
4. Within a few minutes, a reload button should appear. Press it to reload VSCode.
6. Within a few minutes, a reload button should appear. Press it to reload VSCode.
![](/gitbook/assets/vsc_setup_step_4.png)
5. That's it! You've installed the Pymakr Extension for VSCode
7. That's it! You've installed the Pymakr Extension for VSCode
![](/gitbook/assets/vsc_setup_step_5.png)
@@ -36,17 +38,13 @@ Please follow these steps to install the [Pymakr VSCode Extension](https://marke
After installing the Pymakr Plugin, you need to take a few seconds to configure it for first time use. Please follow these steps:
1. Connect your Pycom device to your computer via USB. If you are using an
Expansion Board, and have just finished a firmware upgrade, be sure to **Remove**
**the wire between GND and G23** and reset your device by pressing the button.
1. Connect your Pycom device to your computer via USB.
2. Open Visual Studio Code and ensure that the Pymakr Plugin has correctly installed.
![](/gitbook/assets/vsc_config_step_1-1.png)
3. Click `All commands` on the bottom of the Visual Studio Code window
3. Generally, your device will be auto-detected. If this does not work, click `All commands` on the bottom of the Visual Studio Code window
![](/gitbook/assets/vsc_config_step_2-1.png)
@@ -56,16 +54,4 @@ After installing the Pymakr Plugin, you need to take a few seconds to configure
5. This will list the available serial ports. If Pymakr is able to auto-detect which to use, this will be copied to your clipboard. If not please manually copy the correct serial port.
![](/gitbook/assets/vsc_config_step_4.png)
6. Once again click `All commands`, then click `Pymakr > Global Settings`. This will open a JSON file. Paste the serial address you copied earlier into the field `address` and save the file.
![](/gitbook/assets/vsc_config_step_5-1.png)
7. Finally close the JSON file, click `All commands`, then `Pymakr > Connect` to connect your device. The Pymakr console should show three arrows `>>>`, indicating that you are connected
![](/gitbook/assets/vsc_config_step_6.png)
These settings can also be applied on a per project basis by clicking `All commands` then `Pymakr > Project Settings`. This will open a JSON file which you can edit to enter your desired settings for the currently open project.
>Note: This process is easiest with either a Pycom Expansion Board or a Pytrack/Pysense as the addresses are automatically selected. For external products such as FTDI USB Serial Cables, the serial address may need to be copied manually. Additionally, the reset button on the device may also need to be pressed before a connection message appears.
![](/gitbook/assets/vsc_config_step_4.png)