Pymate: Understanding Virtual and Terminal Pins

Roberto

This guide contains the basic information required to understand the Virtual Pins in the Pymate app:

Before you begin:

Download the Pymate App on your mobile device
Setup your Pycom device using the steps provided in the application (if you have modified your boot.py to automatically connect to your router remove this code before proceeding with the setup or simple put your device in safe boot following this steps)
If you have already setup up your device in the past re-setup it to make sure you have the latest version of the library.

What does the setup do?
The setup stage download 4 files from the Pycom servers and then upload them to your Pycom Device

simple.py: An MQTT Library from the microPython community
boot.py: A custom boot file that will automatically connect your Pycom Device to your router on boot
pymate_library.py: This is in charge of performing the basic board interactions like reading and writing digital and analog values to the different pins, managing the terminal pins and virtual pins.
pymate_basic.py: A basic implementation of the pymate_library. Here you can customize your virtual and terminal pins as well as provide some extra configuration.

What are Virtual Pins?
The Pymate app can read and write analog and digital values from the pins out of the box, but if you require any extra functionality (running a specific code when you press a button on your mobile or changing the color of the an LED from a slider) you will need to implement Virtual Pins.
Virtual pins are hooks that will allow you to run microPython code when a value is received in your Pycom Device.

What is a Terminal Pin?
A terminal pin is an implementation of a virtual pin that dumps the terminal console to a virtual pin. Using a terminal pin will allow you to read and input microPython code directly from your mobile.

How to implement a Virtual Pin (Write) + Example:
Note: As for the moment of this post the only widgets that support virtual write are the button and slider widgets
To implement a Virtual Pin (Write) you will require to edit the pymate_basic.py file located on your device after setting it up with the Pymate app, The file is located in /flash/lib/pymate_basic.py

Here you will find a section commented "Initialize Virtual Pins and Terminal Pins Here",

Step 1:
To begin, first declare a function that you would like to call when the virtual pin is called from the mobile. For example (Warning: This code example will only work in the LoPy and Wipy 2.0)

# Initialize Virtual Pins and Terminal Pins Here
import pycom
def set_led_color(params):
val = int(params[0])
    if (val < 256):
        val = val & 0xFF
    elif (val > 255 and val < 512):
        val = (val << 8) & 0xFF00
    elif (val > 511):
        val = (val << 16) & 0xFF0000
    pycom.rgbled(val)

As you can see in this example you can receive an array of parameters. As for this moment, all the widgets in the Pymate app will only send you one parameter (params[0]) and this parameters will always be of type string. Further widgets might include more complex interaction with Virtual Pins.

Parameter example:

Button Widget: '0' or '1' values
Slider Widget: '0' to 'defined value in the widget'

Step 2
After defining your function, declare it as a virtual write pin, to do so call the add_virtual_pin function in the pymate_library

pymate_library.add_virtual_pin(1,None, set_led_color)

Here we can see the function receives 3 parameters (pin_number, read_function, write_funtion).

Pin numbers can go from 1 to 199
Read_function: None, for the virtual write pins
Write_function: the function you defined in Step 1

Step 3:
Save the file, upload it to your Pycom Device using FTP and reset it.

Step 4
On the Pymate app add a widget an map it to your virtual pin. Click the start button and use your widget. In this example we added a slider widget with min value 0 and max value 767

Recommendations
If you require to debug your code while it is running on the Pycom Device, put a print() on your defined function to read the params[0] value. You can read this print if you connect to your device using on your computer terminal

screen /dev/tty.usbXXXXXXXXXXX 115200

How to implement a Virtual Pin (Read) + Example:
Note: As for the moment of this post the only widgets that support virtual write are: Led, LineChart, BarChart and Display widgets
To implement a Virtual Pin (Read) you will require to edit the pymate_basic.py file located on your device after setting it up with the Pymate app, The file is located in /flash/lib/pymate_basic.py

Here you will find a section commented "Initialize Virtual Pins and Terminal Pins Here",

Step 1:
To begin, first declare a function that you would like to call when the virtual pin is called from the mobile. For example:

# Initialize Virtual Pins and Terminal Pins Here
from uos import urandom
def read_random():
    val = int(urandom(1)[0])
    return val

As you can see in this example, you can return an integer from any function mapped to a virtual pin. Different Widgets will render this value in different ways.

LineChart and BarChart widgets: Will use the value to display one new value for the chart
Display Widget: will show the value in the display as soon as it arrives
Led Widget: If the value is bigger than 0 the led will turn on

Step 2
After defining your function, declare it as a virtual read pin, to do so call the add_virtual_pin function in the pymate_library

pymate_library.add_virtual_pin(1,read_random, None)

Here we can see the function received 3 parameters (pin_number, read_function, write_funtion).

Pin numbers can go from 1 to 199
Read_function: the function you defined in Step 1
Write_function: None for the virtual read pins

Step 3:
Save the file, upload it to your Pycom Device using FTP and reset it.

Step 4
On the Pymate app add a widget an map it to your virtual pin. Click the start button and use your widget

Recommendations
If you require to debug your code while it is running on the Pycom Device, put a print() on your defined function to read the value you are returning from your function. You can read this print if you connect to your device using on your computer terminal

screen /dev/tty.usbXXXXXXXXXXX 115200

Refresh Rate of your Virtual Read Pin
Your virtual read pin function will be called periodically from the mobile app while in run mode. You can set the frequency of this calls while creating the widget from 250ms to 20secs.
If you are performing intensive operations keep in mind that you should adjust your refresh rate accordingly.

How to implement a Terminal Pin + Example:
As said before, a terminal pin is one that will allow you to dump the terminal console to a terminal widget in your mobile device.
To declare a virtual pin as a terminal pin write the following code on the pymate_basic.py file:

pymate_library.add_terminal_pin(1)

This function takes 1 parameter add_terminal_pin(pin_number)

After declaring this, saving your file and uploading it to your Pycom Device you should be able to use the terminal from your mobile phone.
Note: To keep the communication process as simple as posible, you are not able to use autocomplete from the terminal widget in your mobile device.

MainSheet

Hi @Roberto thanks for the sample. where do we find simple.py, boot.py pymate_library.py and pymate_base.py ?

Roberto

Hello @MainSheet,
Download the Pymate App for iOS or participate in the beta version for Android.
When you open the app proceed with the setup of your device. When the setup is completed all the files will be on your device in this folders

/boot.py
/flash/lib/pymate_library.py
/flash/lib/simple.py
/flash/lib/pymate_basic.py

You can access them using FTP

Best,
Roberto

Frida

Pymate for Android downloaded.
In Setup Wizard:
Please select your router (2.4Ghz):

Nothing hapens, what next?

LoneTech

Someone forgot the first step in the app. It demands a login to some unspecified account.

Frida

I am logget in, and I can se my router and my Wipy2 from my PC, so nothing wrong there. But Pymate can't se anything, it is just scanning the network.

LoneTech

Sorry for the confusion, Frida. I didn't mean to imply that was your mistake; what I mean is, when I load this app, all it does is demand a login to an account. It doesn't say where that account is, or what happens if I sign up. It doesn't say a single word about what the app is for, for that matter. On top of that, the signup form is actively fighting back when you try to use it; on my tablet, it draws things on top of each other, and on my phone it covers fields with the on-screen keyboard and disables scrolling so you can't reach the lower fields. I haven't gotten as far as you.

Roberto

Hi @LoneTech,

I'm sorry that you are having problems with the Login on Pymate.
To answer your questions:

The account is created in our server.
The only information stored in our servers as for now is:
a. User Account Details
b. Device List (Name and DeviceID)
c. Widgets (Types, positions, color, names and pins)
User profile (if you provide one after you log into the app

To solve your problem of overlapping object on the login please provide the following information

Device Type: iOS / Android
Device Model: (Ex. Samsung Galaxy Note 4 / iPad mini)
Operative system: (Ex. Android 6.0 / iOS 10)
Do you have the latest version of the app? (Yes / No)
Please provide any other information / Screen you think might be relevant for fixing the issue.

Best,
Roberto

Roberto

Hello @Frida

Really sorry that you are not able to connect to your device.
To help you i will require the following information

Device Type (Android/iOS):
Device Model (Samsung Galaxy Note 4 / iPad Mini)
OS Version (Ex. Android 6.0 / iOS 10)
The device Type you are trying to use (WiPy / WiPy 2.0 / LoPy)
Any other information that you think might be important

As per your post i can tell you that after the setup process you should not be able to see the device anymore from your computer since it should be connected to your router and will no longer appear as an Access Point.
Please answer the questions above so we can check in our side and provide you with further feedback. For now, please retry the device setup process since it seems that some files where not uploaded properly or you introduced the wrong Router/Password. Please notice that the router should be a 2.4Ghz router.

One last note: We are aware of an issue with the setup in the Android Demo of the Pymate app, we are working hard on a fix and will let you know as soon as one is available.

Best,
Roberto

Frida

Device Type (Android/iOS):
Device Model (Samsung Galaxy Note 4 / iPad Mini)
OS Version (Ex. Android 6.0 / iOS 10)
The device Type you are trying to use (WiPy / WiPy 2.0 / LoPy)
Any other information that you think might be important

Phone:

Android
Motorola Moto G(2. generation) with 4G LTE
Android 6.0
Wipy 2.0

In my Mororola.
In Setup Wizard:
Please select your router (2.4Ghz):
In the right side there is a little round ring running, but I can't see any AP.

Phone: older

Android
LG
Android 4.1.2
Wipy 2.0

In my older LG.
In Setup Wizard:
Please select your router (2.4Ghz):
I can choose AP, and set my password, but when I press next my network disappear and it say's Could not connect to the specified network.

I tried

Roberto

@Frida,

Thank you very much for your reply. As for now Pymate Android is in Beta stage, we are still polishing a few bugs, specially related to the Setup Stage.

We have uploaded a new version of the app. I'm not 100% sure that it might help you with your current issue since it SSID lookup was not addressed in that update, but some other bugs with the setup stage where.

We also detected that for devices using 6.0 + you will need to turn off your Network before going trough the setup stage. This is a problem caused by the fact that when Android detects that a Wifi has no internet connection (cant ping goole) it drops the Wifi connection ( ! or x mark on the wifi).

Please download the new Beta version and try setting up your device. I will check with the device models you told me to make sure that there are no other problems going on. As for now we support around more that 11.000 different android devices, so stabilising the app to get it production ready takes a little bit of time.

Thank you for your support during this Beta stage.

Best,
Roberto

Roberto

@Frida,
Its also important that you accepted the right permissions for the app (specially in 6.0+) to check this go to your phone settings and check under apps the pymate app. Location permissions are required by google to be able to scan for wifi networks.

Frida

Thank you very much Roberto.

It is on.
In Settings Personal Location, It also have to be on, while I setup a new device.
Then I can put it off again.
Now I'm on.

But I have to reset the Wipy2 several times, until it gets stable.

Traceback (most recent call last):
 File "boot.py", line 39, in <module>
 File "/flash/lib/pymate_basic.py", line 13, in <module>
 File "/flash/lib/pymate_library.py", line 402, in run
 File "/flash/lib/pymate_library.py", line 377, in _close
 File "/flash/lib/simple.py", line 109, in disconnect
OSError: 128
MicroPython v1.8.6-13-ge1a0670 on 2016-11-18; WiPy with ESP32
Type "help()" for more information.
>>> ets Jun  8 2016 00:22:57

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun  8 2016 00:22:57

rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0x00
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:QIO, clock div:2
load:0x3fff9010,len:8
load:0x3fff9018,len:312
load:0x40078000,len:2348
ho 0 tail 12 room 4
load:0x4009f000,len:1364
entry 0x4009f2f8
rtc v112 Sep 26 2016 22:32:10
XTAL 40M
frc2_timer_task_hdl:3ffd9bd8, prio:22, stack:2048
tcpip_task_hdlxxx : 3ffde3a4, prio:18,stack:2048
phy_version: 123, Sep 13 2016, 20:01:58, 0
pp_task_hdl : 3ffdfbf0, prio:23, stack:8192
mode : softAP(24:0a:c4:00:70:c5)
dhcp server start:(ip: 192.168.4.1, mask: 255.255.255.0, gw: 192.168.4.1)
dhcp server start:(ip: 192.168.4.1, mask: 255.255.255.0, gw: 192.168.4.1)
mode : sta(24:0a:c4:00:70:c4)
n:13 0, o:6 0, ap:255 255, sta:13 0, prof:6
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0

connected with Propeller, channel 13
Traceback (most recent call last):
 File "boot.py", line 39, in <module>
 File "/flash/lib/pymate_basic.py", line 13, in <module>
 File "/flash/lib/pymate_library.py", line 402, in run
 File "/flash/lib/pymate_library.py", line 377, in _close
 File "/flash/lib/simple.py", line 109, in disconnect
OSError: 128
MicroPython v1.8.6-13-ge1a0670 on 2016-11-18; WiPy with ESP32
Type "help()" for more information.
>>> ets Jun  8 2016 00:22:57

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun  8 2016 00:22:57

rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0x00
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:QIO, clock div:2
load:0x3fff9010,len:8
load:0x3fff9018,len:312
load:0x40078000,len:2348
ho 0 tail 12 room 4
load:0x4009f000,len:1364
entry 0x4009f2f8
rtc v112 Sep 26 2016 22:32:10
XTAL 40M
frc2_timer_task_hdl:3ffd9bd8, prio:22, stack:2048
tcpip_task_hdlxxx : 3ffde3a4, prio:18,stack:2048
phy_version: 123, Sep 13 2016, 20:01:58, 0
pp_task_hdl : 3ffdfbf0, prio:23, stack:8192
mode : softAP(24:0a:c4:00:70:c5)
dhcp server start:(ip: 192.168.4.1, mask: 255.255.255.0, gw: 192.168.4.1)
dhcp server start:(ip: 192.168.4.1, mask: 255.255.255.0, gw: 192.168.4.1)
mode : sta(24:0a:c4:00:70:c4)
n:13 0, o:6 0, ap:255 255, sta:13 0, prof:6
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0

connected with Propeller, channel 13

Then after some time, I lose the connection to my phone, and get the promt on the console. I then have to reset several times again, before I can connect.

Keep up the good work.

Happy Beta tester.

crankshaft

Hi;

I am testing wipy2 with the latest firmware and the latest version of pymate.

Using the slider / rgbled example, I am experiencing high latency and then crash / disconnect.

This is the error message, although I have seen other types than 57 & 70 but don't recall what they were.

Error: unknown message type 57, connection closed
Error: unknown message type 70, connection closed

I am printing out the values received and there are intermittent pauses of 10 seconds or more when no data is received and then it all comes in and most times it will then crash.

I have 1 1GB Fibre network connection with excellent connectivity, and I have tried this on 2 different networks with the same result.

I have tried to ping mqtt.pycom.io to see if there was any latency in the connection but pings are understandably blocked by this server.

Any suggestions on the cause / solution ??

troy salt

I'm struggling to get this to work.

After following the instructions seemingly exactly with a wipy2.0 running 1.18.2.r4, I run into an error:
"Warning: Virtual write to unregistered pin 1"

All I did was download the code from wipy2 after setting up pymate, and add:

import pycom
def set_led_color(params):
    val = int(params[0])
    if (val < 256):
        val = val & 0xFF
    elif (val > 255 and val < 512):
        val = (val << 8) & 0xFF00
    elif (val > 511):
        val = (val << 16) & 0xFF0000
    pycom.rgbled(val)

pymate_library.add_virtual_pin(1,None, set_led_color)

right under where it says "# Initialize Virtual Pins and Terminal Pins Here" in the Pymate_basic.py file in the lib.

I can't seem to figure out why this doesn't work since I am following this guide exactly.

Is the only way to upload code through FTP? I seem to be able to download, edit, and re-upload the code through REPL when booted in safe mode. Is this a no-no?

Please HELP!
thanks

Explore Pybytes | Official Documentation | Report a Firmware Bug/Issue | GitHub

Pymate: Understanding Virtual and Terminal Pins

Pycom on Twitter