Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
amotl committed Mar 7, 2019
1 parent f0cf751 commit 684edd0
Show file tree
Hide file tree
Showing 8 changed files with 523 additions and 146 deletions.
185 changes: 76 additions & 109 deletions README.rst
Expand Up @@ -3,134 +3,71 @@ Hiveeyes MPY data logger
########################


***************
Getting started
***************

Configure environment
=====================
Adjust the serial port in the ``Makefile``.

First steps
===========
Install some tooling::

make setup-environment

Connect to REPL shell on device::
************
Introduction
************
Before getting started with this, please `upgrade the Pycom firmware`_
on your device.
After that, be prepared to put ``make recycle``, ``CTRL+C``, ``CTRL+D``
and ``CTRL+X`` into your muscle memory. Otherwise, let's go shopping.

make repl
Pycom MicroPython 1.18.2.r3 [v1.8.6-849-a1641ca] on 2019-02-28; FiPy with ESP32
The `General information about the WiPy`_ on the MicroPython documentation
pages is a good start to read more about the things that will follow.

# General help
>>> help()

# List built-in modules
>>> help('modules')


Control commands
================

Cheatsheet
----------
********
Synopsis
********
::

CTRL-D: PYB: soft reboot
CTRL-X: Exit REPL and rshell
# Setup the development sandbox (once).
make setup

Details
-------
::
# Upload and run sketch.
make recycle

CTRL-A -- on a blank line, enter raw REPL mode
CTRL-B -- on a blank line, enter normal REPL mode
CTRL-C -- interrupt a running program
CTRL-D -- on a blank line, do a soft reset of the board
CTRL-E -- on a blank line, enter paste mode
CTRL-F -- on a blank line, do a hard reset of the board and enter safe boot

*****
Setup
*****
You mean it. Thanks for listening already and enjoy the ride.

rshell
======
::

make rshell
cd /flash
ls
Configuration
=============
Please adjust the serial port in ``config.mk``. YMMV.

Setup development sandbox
=========================
This will install different tools into the local directory which we
consider essentially for efficient MicroPython development.
The programming environment driven through different ``make`` targets
and the accompanying documentation is based on a successful installation
of these tools.
::

rshell --port /dev/tty.usbmodemPye090a1 rsync . /flash
make setup

::

make rshell
*********
Operation
*********

~/hiveeyes-micropython-firmware> boards
pyboard @ pyboard connected Epoch: 1970 Dirs: /flash /pyboard/flash
took 0.001 seconds

::

~/hiveeyes-micropython-firmware> ls /flash/lib
mqtt.py urllib.py


Upload MicroPython firmware
Upload and run your program
===========================
::
This will upload ``boot.py``, ``main.py`` and ``settings.py`` and then
issue a hard reset, so this will essentially run your program from scratch
as it will likewise happen in the real world::

make sync-all
took 40.170 seconds
make recycle


****************
Firmware upgrade
****************

Pycom Upgrader application
==========================
Install the Pycom Upgrader application for your platform.
See also:

- https://pycom.io/downloads/
- https://docs.pycom.io/gettingstarted/installation/firmwaretool.html

.. todo:: Add command for ArchLinux et al.

Prepare
=======

Conveniency::

alias pycom-fwtool-cli='/Applications/Pycom\ Firmware\ Update.app/Contents/Resources/pycom-fwtool-cli'

Check board connectivity::

pycom-fwtool-cli list
/dev/cu.usbmodemPye090a1 [Expansion3] [USB VID:PID=04D8:EF98 SER=Pye090a1 LOCATION=20-2]

Acquire recent firmware binaries::

# https://software.pycom.io/downloads/FiPy.html
wget https://software.pycom.io/downloads/FiPy-1.20.0.rc7.tar.gz

Flash firmware
==============
See also: https://docs.pycom.io/advance/downgrade.html

1. Get device into programming mode by holding down the button while powering the device.
2. Upload firmware::

pycom-fwtool-cli --verbose --port /dev/tty.usbmodemPye090a1 flash --tar FiPy-1.20.0.rc7.tar.gz

3. Power-cycle the device

4. Connect to REPL shell on device::
***************
Getting started
***************
Connect to REPL shell on device::

make repl
PyomMiroPython 1.20.0.rc7 [v1.9.4-2833cf5] on 2019-02-08; FiPy with ESP32
Pycom MicroPython 1.18.2.r3 [v1.8.6-849-a1641ca] on 2019-02-28; FiPy with ESP32

# General help
>>> help()
Expand All @@ -139,8 +76,38 @@ See also: https://docs.pycom.io/advance/downgrade.html
>>> help('modules')


MicroPython control commands
============================
At this point, you should take a minute to have a look at
`getting started with Pycom MicroPython`_. It will be worth it as it will walk
you through essential function keys you will need after taking the red pill.


***************
Troubleshooting
***************
Please have a look at `Hiveeyes MPY data logger troubleshooting`_.


*******
Credits
*******
- micropython-lib
- Microhomie
- https://github.com/pycom/pycom-libraries
- https://github.com/micropython/micropython-lib
- https://github.com/daq-tools/terkin/tree/master/src/micropython
- The RaTrack firmware (undisclosed yet)
- https://github.com/microhomie/microhomie
- https://github.com/ClemensGruber
- https://github.com/hiveeyes/arduino
- https://github.com/jacobron/EasyHive_Pycom_Shield/tree/master/V1.0/software
- https://github.com/walterheisenberg/hivewatch_esp32
- https://github.com/Quernon/honeypi
- https://github.com/geda/hx711-lopy

Standing on the shoulders of giants. Thank you so much!


.. _upgrade the Pycom firmware: https://github.com/hiveeyes/hiveeyes-micropython-firmware/blob/master/doc/pycom-firmware-upgrade.rst
.. _General information about the WiPy: https://docs.micropython.org/en/latest/wipy/general.html
.. _getting started with Pycom MicroPython: https://github.com/hiveeyes/hiveeyes-micropython-firmware/blob/master/doc/pycom-getting-started.rst
.. _Hiveeyes MPY data logger troubleshooting: https://github.com/hiveeyes/hiveeyes-micropython-firmware/blob/master/doc/troubleshooting.rst
6 changes: 5 additions & 1 deletion doc/backlog.rst
Expand Up @@ -2,12 +2,16 @@
Hiveeyes MPY data logger backlog
################################

- [o] make recycle scope=full
- [o] Solid configuration system
- [o] Use pure-Python "urllib" without dependency to "libpcre"
- [o] Appropriate logging
- [o] Periodic servicing tasks
- [o] Poll WiFi connection
- [o] Timekeeping (NTP)
- [o] Timekeeping, use RTC and NTP
- [o] Add Watchdog timer
- [o] Basic telemetry: Battery, Temperature, Hall-Sensor
- [o] Upload .mby code through mby-cross
- [o] Docs, docs, docs
- [o] Add "wait_for_network", "check_network"
- [o] Better ordering for ``os.uname()`` attributes
128 changes: 128 additions & 0 deletions doc/one-cycle.rst
@@ -0,0 +1,128 @@
::

$ time make recycle
.venv3/bin/rshell --port /dev/tty.usbmodemPye090a1 --buffer-size 2048 --timing --file tools/upload-requirements.rshell
Using buffer-size of 2048
Connecting to /dev/tty.usbmodemPye090a1 (buffer-size 2048)...
Testing if ubinascii.unhexlify exists ... Y
Retrieving root directories ... /flash/
Setting time ... Mar 07, 2019 03:49:38
Evaluating board_name ... pyboard
Retrieving time epoch ... Jan 01, 1970
Unable to create /flash/lib/terkin
took 0.531 seconds
took 12.812 seconds
Unable to create /flash/lib/hiveeyes
took 0.533 seconds
took 3.463 seconds
Unable to create /flash/dist-packages
took 0.522 seconds
took 6.568 seconds
.venv3/bin/rshell --port /dev/tty.usbmodemPye090a1 --buffer-size 2048 --timing --file tools/upload-sketch.rshell
Using buffer-size of 2048
Connecting to /dev/tty.usbmodemPye090a1 (buffer-size 2048)...
Testing if ubinascii.unhexlify exists ... Y
Retrieving root directories ... /flash/
Setting time ... Mar 07, 2019 03:50:05
Evaluating board_name ... pyboard
Retrieving time epoch ... Jan 01, 1970
took 3.674 seconds
took 1.850 seconds
took 2.018 seconds
took 1.839 seconds
Entering REPL. Use Control-X to exit.
>
ycom MicroPython 1.20.0.rc7 [v1.9.4-2833cf5] on 2019-02-08; FiPy with ESP32
Type "help()" for more information.
>>>
>>> import machine
>>> took 1.124 seconds
Entering REPL. Use Control-X to exit.

>>> machine.reset()
ets Jun 8 2016 00:22:57

rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:1
load:0x3fff8028,len:8
load:0x3fff8030,len:2064
load:0x4009fa00,len:0
load:0x4009fa00,len:19208
entry 0x400a05f8
Initializing filesystem as FatFS!
INFO: Python module search path is: ['', '/flash', '/flash/lib', 'dist-packages']
=========================
BOB MPY data logger 0.0.0
=========================
CPU freq 160.0 MHz
Device id 807d3ac342bc

---------------------------------------------
System memory info (in bytes)
---------------------------------------------
MPTask stack water mark: 6276
ServersTask stack water mark: 3204
LoRaTask stack water mark: 3540
SigfoxTask stack water mark: 2936
TimerTask stack water mark: 2008
IdleTask stack water mark: 592
System free heap: 333344
---------------------------------------------

lorawan: 1.0.2
machine: FiPy with ESP32
nodename: FiPy
release: 1.20.0.rc7
sigfox : 1.0.1
sysname: FiPy
version: v1.9.4-2833cf5 on 2019-02-08

[0.06617132] Starting networking
WiFi STA: Starting connection
WiFi STA: Connecting to network "BKA Ueberwachungswagen"
WiFi STA: Succeeded
Networking status: mac=(sta_mac=b'\x80}:\xc3B\xbc', ap_mac=b'\x80}:\xc3B\xbd'), ifconfig=('192.168.178.172', '255.255.255.0', '192.168.178.1', '192.168.178.1'), status=None
Networking established
[6.812766] Starting telemetry
WARNING: libpcre is not available on this platform. TelemetryClient will talk MQTT only.
Telemetry channel URI: mqtt://swarm.hiveeyes.org/hiveeyes/testdrive/area-23/node-1
Starting Terkin TelemetryClient
[10.68297] Registering Terkin sensors
[10.68667] Registering Hiveeyes sensors
[10.69024] Registering BOB sensors

[10.69405] BOB loop
[10.69685] Terkin mainloop
Reading sensor "DummySensor"
Telemetry transport: MQTT over TCP over WiFi
MQTT topic: hiveeyes/testdrive/irgendwas/baz/data.json
MQTT payload: {"humidity": 83, "temperature": 42.84}
[11.58851] Telemetry data successfully transmitted

[12.59279] BOB loop
[12.59646] Terkin mainloop
Reading sensor "DummySensor"
MQTT topic: hiveeyes/testdrive/irgendwas/baz/data.json
MQTT payload: {"humidity": 83, "temperature": 42.84}
[12.61107] Telemetry data successfully transmitted

[13.61602] BOB loop
[13.61977] Terkin mainloop
Reading sensor "DummySensor"
MQTT topic: hiveeyes/testdrive/irgendwas/baz/data.json
MQTT payload: {"humidity": 83, "temperature": 42.84}
[13.63415] Telemetry data successfully transmitted
Traceback (most recent call last):
File "main.py", line 58, in <module>
File "main.py", line 53, in main
File "/flash/lib/terkin/datalogger.py", line 36, in start
File "/flash/lib/terkin/datalogger.py", line 50, in _mainloop
KeyboardInterrupt:

took 26.421 seconds

real 1m6.792s
user 0m0.716s
sys 0m0.210s

0 comments on commit 684edd0

Please sign in to comment.