Documentation

Nanpy Extension

The Nanpy extension allows you to connect to microcontrollers (ESP8266, ESP32, Arduino) and control them via serial or WiFi.

Warning

Deprecated in v0.11.0 — will be removed in a future release. The nanpy library has not been updated since 2020 and may not function correctly on Python 3.9+. This extension is unsupported and there is no direct replacement at this time.

Overview

Nanpy allows you to connect to a microcontroller and control it via serial or WiFi. Supported microcontrollers include ESP8266, ESP32, and Arduino.

Installing Nanpy

Nanpy allows us to issue commands over serial or WiFi to our device from our controller running MudPi. You will need to compile and install the nanpy firmware on your device using the Arduino IDE. Please be sure to use the custom MudPi fork of nanpy for ESP32 support.

When setting up Nanpy you can choose to use serial or WiFi for the connection. To use WiFi you need to add your network credentials in the firmware before you flash. If using serial, you can connect your Nanpy device through a USB slot from your MudPi controller using a USB to TTL serial module.

Tip

If you are using WiFi, the device should automatically connect to the network once powered. You can use the serial monitor of the Arduino IDE to get the IP address or locate it through your router admin page.

Extension Configuration

The nanpy connection config is stored on the extension level to consolidate the connection logic. Components can reference this connection to prevent multiple connection attempts.

Option	Type	Required	Description
`key`	String	Yes	Unique slug id for the connection. Referenced by interfaces.
`address`	String	Yes	USB device path (e.g. `/dev/ttyUSB0`) or IP address (e.g. `192.168.2.150`).
`use_wifi`	Boolean	No	Set to `true` to use WiFi instead of serial. Default: `false`

Connection Config Example

mudpi.config.json

{
  "nanpy": [
    {
      "key": "nanpy_1",
      "address": "192.168.2.150",
      "use_wifi": true
    },
    {
      "key": "nanpy_2",
      "address": "/dev/ttyUSB0"
    }
  ]
}

Note

You can run ls /dev in your terminal to get a listing of serial devices. Typically the value you're looking for is one of /dev/AMA0, /dev/ttyUSB0, or /dev/ttyUSB1.

Sensor Interface

Provides a sensor for reading from a microcontroller pin. Arduinos and ESPs have a larger range of supported sensor types due to analog GPIO.

Option	Type	Required	Description
`key`	String	Yes	Unique slug id for the sensor
`node`	String	Yes	`key` of the node connection to use.
`pin`	Integer	Yes	GPIO pin number on the microcontroller the sensor is connected to.
`type`	String	Yes	Type of sensor. Options: `gpio`, `dht`
`name`	String	No	Friendly name of the sensor. Useful for UI.
`analog`	Boolean	No	Set to `true` if the pin is analog. Default: `false`
`classifier`	String	No	Classifier override for sensor formatting.

DHT Sensor Settings

Additional settings for the dht sensor type:

Option	Type	Required	Description
`model`	String	No	Model of DHT device to use. Options: `11`, `22`, or `2302`. Default: `11`

Sensor Config Example

mudpi.config.json

{
  "sensor": [
    {
      "key": "nanpy_gpio_d12",
      "interface": "nanpy",
      "node": "nanpy_1",
      "name": "GPIO Pin D12",
      "type": "gpio",
      "pin": 12,
      "analog": false
    }
  ]
}

Control Interface

Attach a control to a microcontroller GPIO. Arduinos and ESPs have analog GPIO support and allow access to a larger range of control options.

Option	Type	Required	Description
`key`	String	Yes	Unique slug id for the component
`node`	String	Yes	`key` of the node connection to use.
`pin`	Integer	Yes	GPIO pin to use on board, e.g. `12`
`name`	String	No	Friendly display name of component. Useful for UI.
`type`	String	No	Type of control behavior. Options: `button`, `control`, or `potentiometer`. Default: `button`
`analog`	Boolean	No	Set to `true` if the pin is analog. Default: `false`
`buffer`	Integer	No	A buffer to apply to analog readings to prevent many state updates for small variances in readings.

Control Config Example

mudpi.config.json

{
  "control": [
    {
      "key": "nanpy_control_a2",
      "interface": "nanpy",
      "node": "nanpy_1",
      "name": "Potentiometer Pin A2",
      "type": "potentiometer",
      "pin": 2,
      "analog": true,
      "buffer": 15
    }
  ]
}

Toggle Interface

Provides a toggle that can turn a nanpy device GPIO pin on or off.

Option	Type	Required	Description
`key`	String	Yes	Unique slug id for the component
`node`	String	Yes	`key` of the node connection to use.
`pin`	Integer	Yes	GPIO pin to use on board, e.g. `12`
`name`	String	No	Friendly display name of component. Useful for UI.
`max_duration`	Integer	No	Failsafe duration (in seconds) to turn off toggle after. 0 means off. Default: `0`
`invert_state`	Boolean	No	Set to `true` if toggle is off when pin is in HIGH state. Default: `false`

Toggle Config Example

mudpi.config.json

{
  "toggle": [
    {
      "key": "nanpy_toggle_D12",
      "interface": "nanpy",
      "node": "nanpy_1",
      "name": "LED - Pin D12",
      "pin": 12,
      "max_duration": 360,
      "invert_state": false
    }
  ]
}

Character Display Interface

Connect and control a character display over I2C to display messages.

Option	Type	Required	Description
`key`	String	Yes	Unique slug id for the component
`address`	Integer	Yes	The I2C address of the display (as an integer). Default: `39`
`node`	String	Yes	`key` of the node connection to use.
`type`	String	No	What type of display is connected. Options: `i2c` or `gpio`. Default: `i2c`
`default_duration`	Integer	No	Time in seconds for messages to be displayed on screen by default when no duration is provided. Default: `5`
`max_duration`	Integer	No	The max time in seconds that messages can be on the screen. Default: `60`
`message_limit`	Integer	No	Number of messages to accept into queue before overwriting. Default: `20`
`topic`	String	No	Channel to listen for events on. Default: `char_display/{key}`
`name`	String	No	Friendly display name of component. Useful for UI.

Character Display Config Example

mudpi.config.json

{
  "char_display": [
    {
      "key": "i2c_display_1",
      "interface": "nanpy",
      "node": "nanpy_1",
      "address": 39,
      "name": "I2C LCD Display",
      "type": "i2c",
      "max_duration": 30,
      "default_duration": 10,
      "topic": "char_display/i2c_display_1",
      "message_limit": 20
    }
  ]
}

Previous ← MQTT Extension Next NFC Extension →