Operate the Terkin-Sandbox using the MicroTerkin Agent

:warning: Note: This document supersedes the documentation at Operate the Hiveeyes MicroPython Datalogger sandbox ff. in form of a living document until further notice. At some time in the future, this will be refactored back to the original documentation after becoming mature enough.


This part of the documentation covers the installation and operation of the development environment for the Terkin Datalogger Firmware. The first step to using any software package is getting it properly installed. Please read these sections carefully.

Getting started

  1. For setting up the sandbox environment, please follow the documentation at Setup Hiveeyes MicroPython Datalogger sandbox thoroughly.

  2. After the baseline setup works for you, you will be happy to read about how a typical development cycle works when hacking within the sandbox. The next section of this document outlines important details about these aspects, please read this section attentively.

Refresh environment

# Update sources
git pull

# Setup environment
make setup

Connect and prepare device

# Attach device to USB
echo "Ready."

# Inquire serial ports
make list-serials

# Define USB port
export MCU_PORT=/dev/cu.usbmodemPy001711

# Verify board communication
make list-boards

# Install most recent development firmware for FiPy devices
# 1.20.0.rc11 [v1.9.4-0a38f88] on 2019-05-14
make install-pycom-firmware

# Format filesystem partition with LittleFS
make format-flash

Bring device into local network

… and get hold of it.

There are two variants here. The first variant is for bringing an unprovisioned or crashed device into the local network in an ad hoc manner. The second variant outlines how to pull a device already running in live mode from deep sleep and how to attach to it over the network.

Please remember the device is still connected using USB here, so defining the serial port is obligatory.

# Define USB port
export MCU_PORT=/dev/cu.usbmodemPy001711

1. Start networking for an unprovisioned device and get IP address

There are two ways. Either

a) Connect your workstation to the access point the device is creating by factory default. See Wie bekomme ich bei Erst-Inbetriebnahme des FiPys meine WLAN-Zugangsdaten aufs Gerät?. You can find out about its IP address without network scanning by invoking

make ip-address

b) Make the device connect to your local network and print out its IP address by invoking

make connect-wifi ssid=YourNetwork password=YourPassword

c) Make the device spin up a WiFi access point by invoking

make provide-wifi

We are collecting the factory default credentials at Wie bekomme ich bei Erst-Inbetriebnahme des FiPys meine WLAN-Zugangsdaten aufs Gerät? - #5 by Andreas

2. Discover live device on the network, pull it into maintenance mode and get IP address

To learn about the background and concept of live- vs. maintenance-mode, we recommend to take a short look at Wartungsmodus für den Terkin-Datenlogger ff.

The designated utility for this job is Terkin Agent, which gives you reasonable convenience and peace of mind by pulling the right strings for you.

# Discover device and pull it into maintenance mode
make terkin-agent action=maintain

The MicroTerkin Agent will keep running in order to monitor the local network for IP address changes of devices of interest designated through their respective hardware MAC address. When finding a matching device, it will put its IP address into the file terkin/floatip for other programs to pick up.


Detailed steps about how to install this software friend are available within the “Setup” section at Wartungsmodus für den Terkin-Datenlogger.

Quick development iterations from the command line


The development cycle has been improved recently. After discovering the device on the local network through the MicroTerkin Agent, it will put its IP address into a local file ".terkin/floatip" [1]. From there, the file synchronization/upload tools can pick it up for efficiently transferring files using FTP.


You might want to prepare these guys in individual terminals as some of them behave like a daemon actually.

# 1. Terminal: Run the MicroTerkin Agent
make terkin-agent action=monitor

# 2. Terminal: Start the console to watch logging output
make console

# 3. Terminal: Transfer files over the network using FTP
make recycle-ng

# 3.b Variant: Use mpy-cross for ahead-of-time bytecode compilation
make recycle-ng MPY_CROSS=true MPY_TARGET=pycom MPY_VERSION=1.9.4

# 4. Terminal: Send request to the HTTP API
http "http://$(cat .terkin/floatip)/status"


Uploading the source code files to the device efficiently is easy and boils down to

# Synchronize files over the IP network
make recycle-ng

It will transfer the source code files using FTP and restart the device using the HTTP API. [2]

If you don’t run the MicroTerkin Agent [3], you can always put the IP address of your device into the .terkin/floatip file and everything will be the same [4].

Have fun!

  1. This is just a basic implementation we will expand later. Ping @roh. ↩︎

  2. There’s no need to think about "export MCU_PORT={ip address}" anymore, just fire up the MicroTerkin Agent and you are set. ↩︎

  3. As it is currently rather heavyweight on dependencies, we would understand that. ↩︎

  4. You can pin your MAC address to a specific IP address to keep it stable, so there is no need for the MicroTerkin Agent at all. However, you will need the permissions to manage your local WiFi router in order to perform such operations. ↩︎

A post was merged into an existing topic: MicroPython-Firmware schmirgeln (240er)

A post was merged into an existing topic: MicroPython-Firmware schmirgeln (240er)

6 posts were merged into an existing topic: Entwicklung der Terkin-Sandbox

3.b Variant: Use mpy-cross for ahead-of-time bytecode compilation

MicroPython 1.9.4 on Pycom / ESP32

MicroPython 1.11 on Pycom / ESP32

make recycle-ng MPY_CROSS=true MPY_TARGET=pycom MPY_VERSION=1.11

MicroPython 1.11 on pyboard-D / STM32

make pyboard-recycle MPY_CROSS=true MPY_TARGET=pyboard-native MPY_VERSION=1.11