Cutipy-MicroPython Bluetooth LE demo

2020-02-13T15:56:45Z

Kyoungmeyer: Add instructions for some new features to the script

==Intro==
Here we will demonstrate basic Bluetooth LE (low energy) connectivity between an android device and a CutiPy running MicroPython. The application will connect to the CutiPy via the onboard RS9116 radio module, once connected the user can 'wirelessly' toggle an led and send text messages to the LCD.

===Required Materials===
<cl>
1. Android device (Smartphone)
* CutiPy device running MicroPython
* A personal computer
* [http://git.emacinc.com/micropython-public/micropython-helper-scripts/blob/master/blechat.py blechat.py script]
</cl>

===Steps===

'''ON YOUR PC:'''
<cl>
1. Connect your CutiPy to your personal computer using a microUSB cable ([[ Cutipy_Getting_Started | Steps Covered Here ]])
* Copy blechat.py into the CutiPy drive
* Reset your CutiPy board to update the file system
* Establish a REPL terminal connection ([[ Cutipy_Getting_Started | Steps Covered Here ]])
* Enter the following commands into the REPL terminal to launch the ''CutiPy's'' bluetooth application
<syntaxhighlight lang=python>
import blechat
ble = blechat.BleChat('EMAC Demo') # 'EMAC Demo' can be any string less than about 16 chars
ble.start(demo=True)
</syntaxhighlight>

The CutiPy bluetooth connection should now be discoverable.
</cl>
'''ON YOUR ANDROID DEVICE:''' 
<cl>
1. Download the BLE Scanner App from the Google '''Play Store'''
* Open the app
* Find the '''EMAC Demo''' entry. It will have the Alias ''cutipy'' 
[[File:BLE_SCANNER_1.jpg|300px|left|thumb|Figure 1: BLE SCANNER APP]] 

 

* Click '''CONNECT'''
* On the next screen, click the arrow next to '''Custom Service'''
* Clicking on the ‘W’ button (Indicated by red arrow in Figure 2) will bring up a text entry box that will send text to the CutiPy LCD screen
[[File:BT_SCANNER_2.PNG|300px|left|thumb|Figure 2: BLE SCANNER APP]] 

 

* Selecting ''Byte Array'' and sending 0001 will turn on LED1, while sending 0000 will turn it off.
* The text 'clear' can be sent to the clear the LCD, 'exit' can be sent to stop the app.

[[File:BT_SCANNER_3.jpg|300px|left|thumb|Figure 3: BLE SCANNER APP]] 

* Clicking on the 'R' button next to the 'N' button will read the status of Switch 1.
* Clicking on the bottom 'R' button will read a random number generated by the CutiPy's hardware RNG. 

</cl>

Cutipy Web Browser

2020-01-10T16:23:07Z

Kyoungmeyer:

{{#seo:
|title=Cutipy Web Browser
|titlemode=append
|keywords=Cutipy Web Browser
|description=The following page can be used to start serving web pages from a Cutipy.
}}



This page outlines a basic guide to getting starting serving web pages from a Cutipy.







=== Required Equipment ===
<cl>
1. One CutiPy Board
* One microUSB cable
* One MicroSD Card
* A Desktop/Laptop running Linux or Windows
</cl>

{{:Templateimpl:geninfo | initials=KY | title=Cutipy Web Browser | desc=The following page can be used to start serving web pages from a Cutipy. | project=OE 5.0 }}
Running a web browser on the Cutipy is fairly simple, and can be accomplished by using the PicoWebSrv project. This project is primarily aimed at the EMAC CutiPy board with the RS9116 module onboard. PicoWebSrv allows serving of standard webpages (html, css, javascript), as well as hosting a simple REST API implementation.

With only one required file, it is very easy to integrate with new or existing projects.
* ''picoWebSrv.py'' - The Actual Web server
* ''picoMimetypes.py'' - (Optional) Full list of mimetypes for the Content-Type: header line
Currently the server only has support for GET and POST requests.




{{:Templateimpl:using | initials=KY | title=Developing with the Cutipy Web Server | desc=The following page can be used to start serving web pages from a Cutipy. | project=OE 5.0 }}
PicoWebSrv has just one external MicroPython library requirement:
* [https://github.com/micropython/micropython-lib/blob/master/logging/logging.py logging.py] - '''Note:''' This will be included in all standard EMAC MicroPython builds, starting with the next major release.
=== Basic Web Server ===
To run a basic web server from the Cutipy, use the following instructions. These instructions assume that you are storing your webpage files on an SD card attached to the Cutipy.
<cl>1. Remove the SD card from the Cutipy, if already inserted.
* Connect the SD card to the host PC.
* Place web page files on the SD card in the '''www''' directory (The can be downloade HERE.)
* Connect the Cutipy to the host PC via a USB cable. See [[Cutipy_Getting_Started | The getting started page]].
* Create an empty file (NO FILE EXTENSION) called ''SKIPSD'' CutiPy's flash memory (appears as flash drive device '''PYBFLASH''' on your PC)
* Edit boot.py in the flash memory and add the following lines.
{{note|To prevent file corruption, it is recommended that all edits occur outside of the CutiPy's flash memory. For example when editing boot.py, first copy the file to your desktop, make the edits to the desktop copy and then copy the file back to CutiPy flash memory}}
<syntaxhighlight lang=python>
import uos
try:
uos.mount(pyb.SDCard(), '/sd')
except Exception:
pass
</syntaxhighlight>
* Place the PicoWebSrv files (''picoWebSrv.py'' and '''Optionally''' ''picoMimetypes.py'') flash memory as well as ''logging.py'' . 

When it's all said and done, you CutiPy's drive contents ('''PYBFLASH''') should look similar to the following (note logging.py may not be required in future CutiPy firmware releases): 
[[File:PYBFLASH.PNG]] 

And your SD cards contents should only contain the the www directory: 
[[File:MicroSD.PNG]] 
* Disconnect the Cutipy, insert the SD card, then reconnect the Cutipy.
* Run the following commands to start the server.
<syntaxhighlight lang=python>
import network
import picoWebSrv

nic = network.RS9116()
nic.init()
nic.connect('SSID', 'PASSWORD')

host_ip = nic.ifconfig()[0]
pws = picoWebSrv.PicoWebSrv(host_ip, 80, file_location='/sd/www/')
pws.start()
</syntaxhighlight>
</cl>
The web pages placed on the SD card will now be served at the IP of the Cutipy. The IP will be displayed on the Cutipy LCD if populated, it will also be printed on the REPL as follows

{{clo}}
>>> INFO:picoWebSrv:Simple Webserver Running at: 10.0.6.153:80
{{clos}}

Where in this case 10.0.6.153 is the IP address ('''Your IP address may be different'''). Copy and paste this IP address into your web-browser's address bar to view the webpage.
=== REST (Representational State Transfer) Server ===
To start a server with some REST API calls, preform the same steps as with the Basic Web Server, but stop before the last step. You will need to register some functions and endpoints for the API calls before starting the server. This process is illustrated below.

<syntaxhighlight lang=python>
import network
import picoWebServer
import pyb
import ujson

def get_switch(var_list):
if var_list:
switch_num = var_list[0] # (e.g. '/get_switch/1')
else:
switch_num = 1

sw = pyb.Switch(switch_num)

if sw():
response_data = ujson.dumps({'status': 'pressed'})
else:
response_data = ujson.dumps({'status': 'not_pressed'})

return response_data.encode('utf-8')

def led_control(json_dict):
try:
led_num = json_dict['number']
except KeyError:
led_num = 1
led = pyb.LED(led_num)
try:
led_action = json_dict['action']
except KeyError:
led.toggle()
else:
if led_action == 'on':
led.on()
elif led_action == 'off':
led.off()
elif led_action == 'toggle':
led.toggle()
else:
raise ValueError
if led.intensity() == 255: # CutiPy reports 255 as off. LED pins sink current, instead of source.
response_data = ujson.dumps({'status': 'off'})
else:
response_data = ujson.dumps({'status': 'on'})

return response_data.encode('utf-8')

nic = network.RS9116()
nic.init()
nic.connect('SSID', 'PASSWORD')

host_ip = nic.ifconfig()[0]
pws = picoWebSrv(host_ip, 80, file_location='/sd/www/')
pws.add_rest_function('GET', '/get_sw', get_switch)
pws.add_rest_function('POST', 'led_ctrl', led_control)
pws.start()
</syntaxhighlight>
This will start a server with an API call listening for GET at ''/get_sw'' and a call listening for POST at ''led_ctrl''. For more information about these calls, see the library documentation [http://git.emacinc.com/Micropython/PicoWebSrv here].

You can find a file with the above REST function definitions (plus additional functions), [http://git.emacinc.com/kyoungmeyer/PicoTestSite/raw/master/restAPIFuncts.py here]. This file just needs to be imported, then the included functions can be set as REST API calls.

==== Integration with Existing Project ====

This webserver can easily be integrated with existing projects, that need a REST API endpoint. The only extra code that would need written is some wrapper functions (that call existing functions) that take and return the correct parameters expected by the webserver's REST parsing. The [http://git.emacinc.com/kyoungmeyer/PicoTestSite/raw/master/restAPIFuncts.py restAPIFuncts.py] file should provide a good example of this, the functions wrap calls to the various 'pyb.' functions.

=== Real World Example ===

The following is an example of how to set up a webserver instance on a CutiPy, that will restart itself if someone manages to crash the server. Pressing <Ctrl-C> on the REPL terminal will stop the server (you may need to press it more than once). The following is two separate files, the names are indicated by the comment at the top of the block. In ''webserver.py'', replace 'SSID' and 'PASSWORD' with the SSID and PASSWORD of your WiFi network, respectively.

Place these two files, the PicoWebSrv files, and the [http://git.emacinc.com/kyoungmeyer/PicoTestSite/raw/master/restAPIFuncts.py restAPIFuncts.py] file on the CutiPy's flash memory (appears as flash drive device '''PYBFLASH''' on your PC). Download and place the ''www/'' directory from [http://git.emacinc.com/kyoungmeyer/PicoTestSite/repository/archive.zip?ref=master this zip file] onto the SD card (as show in the above sections). After editing the ''main.py'' file, reset the CutiPy, and the websever will be running. The IP address will be printed on the REPL.
<syntaxhighlight lang=python>
# webserver.py

import pyb
import network
import logging
import picoWebSrv
import restAPIFuncts

def webserver():
nic = network.RS9116()
nic.init()
nic.connect('SSID', 'PASSWORD')

host_ip = nic.ifconfig()[0]
pws = picoWebSrv.PicoWebSrv(host_ip, 80, file_location='/sd/www/')
pws.add_rest_function('POST', 'led_control', restAPIFuncts.led_control)
pws.add_rest_function('GET', 'get_switch', restAPIFuncts.get_switch)
pws.add_rest_function('GET', 'get_led', restAPIFuncts.get_led)
pws.start()

def run():
while True:
try:
webserver()
except KeyboardInterrupt:
break
except Exception as e:
print(e)
continue

</syntaxhighlight>
<syntaxhighlight lang=python>
# main.py

import webserver

webserver.run()
</syntaxhighlight>

The ''restAPIFuncts.py'' file can be edited to include additional functions of your choosing, and additional REST endpoints can be added with more calls to ''.add_rest_function()''.

{{:Templateimpl:whatnext | initials=BS | title=Getting Started with the EMAC OE SDK | desc=Basic tutorial for using the EMAC OE SDK. | project=OE 5.0 }}

[http://git.emacinc.com/micropython-public/micropython-doc CutiPy Micropython Documentation]

[[ Cutipy_Test | Cutipy Test Software ]]

[[ Cutipy-MicroPython Bluetooth LE demo | Cutipy-MicroPython Bluetooth LE demo ]]

[[ Micropython | Micropython ]]

[[CutiPy-Installing_MicroPython_Firmware | CutiPy-Installing Micropython Firmware]]

2016-01-19T19:33:21Z