upy-lab/README.md

# MicroPython ESP8266

## Installation
You will want to make sure you are installing the latest version of [Micropython](hhttps://micropython.org/). Download the appropriate [.bin for your chip](https://micropython.org/download) and flash it to your board using the [esptool](https://github.com/espressif/esptool). You will most likely need the UART driver 

```
pip install esptool
```

### Flashing your board

First be sure to erase the flash:

```
esptool.py -p /dev/tty.SLAB_USBtoUART erase_flash
```

Then you will need to write the flash to your board. Be sure to connect with an appropriate baud rate:

```
esptool.py --port /dev/tty.SLAB_USBtoUART --baud 115200 write_flash --flash_size=detect 0 esp8266-20170108-v1.8.7.bin

```

### Connecting to your board

If you are using a mac just leverage the `screen` program:

```
screen /dev/tty.SLAB_USBtoUART 115200
```

This should connect you to the boards REPL

## Connecting to the network

PLACEHOLDER

## Code files

Micropython provides a "Virtual" filesystem for you code and collateral (config files etc.).
 
There are two files that you should take note of `boot.py` and `main.py`. The `boot.py` file will be executed immediately as the interpreter is brought online. It is here that we can place code to connect to a network for example. The `main.py` file should contain the entry point for your Micropython code. This will typically follow the same "Initialize" and enter "While Loop" pattern of code that you see if Arduinos

## Extras

An excellent source for additional "Standard Library" like code can be found at [Micropython-lib](https://github.com/micropython/micropython-lib).

For shipping up code to you board I highly suggest using either the [Pycharm Pluggin](https://blog.jetbrains.com/pycharm/2018/01/micropython-plugin-for-pycharm/) or the [ampy](https://github.com/adafruit/ampy) modul
e tool from adafruit. 

```
ampy --help

ampy -p /dev/tty.SLAB_USBtoUART -b 115200 ls
```

See the basic directory within this project for more detailed usage of the ampy package. 

## MQTT on Hassio

Assuming you have [Hassio installed](https://www.home-assistant.io/getting-started/) (on a raspberry Pi3 for example). You will find the [official MQTT broker](https://www.home-assistant.io/docs/mqtt/broker/) documentation lacking in that small amount of detail that will get you up and running. This section is supposed to help take you that final mile.

### The MQTT Broker

Let's start assuming you are going to use the downloadable [MQTT broker](https://www.home-assistant.io/addons/mosquitto/) from the add-on store. You will also want to have the [configurator package](https://www.home-assistant.io/addons/configurator) installed too. Open up the configurator web-gui and find your `/config/configuration.yaml` file and addc the following entry at the bottom of the file:

```yaml
#MQTT Setup
mqtt:
 broker: 0.0.0.0
 port: 1883
```

This will ensure that your broker properly configured. Now just make sure that you set the `Start on boot` to True in the addon details and restart your home-assistant.

### An MQTT Sensor

Once again you may be a little confused by the official documentation for setting up an [MQTT sensor](https://www.home-assistant.io/components/sensor.mqtt/). Assuming you are using the sample photoresitor light sensor that is included in this repo. Go back to your `/config/configuration.yaml` and this entry:

```yaml
#MQTT Light Sensor
sensor office_light:
  - platform: mqtt
    name: "Office Light"
    unit_of_measurement: "No."
    # Note your esp8266 will have a different MAC id. You can find the sensor's full topic path in the logs of the MQTT add-on
    state_topic: "light/esp8266_aa00f800"
    # Our json is a simple single value extracted with this jinja2 template
    # More templating info can be found here https://www.home-assistant.io/docs/configuration/templating/#processing-incoming-data
    value_template: "{{value_json.payload}}"
    # Material design icons https://cdn.materialdesignicons.com/2.3.54/
    icon: mdi:lightbulb-on-outline
```

This should create an MQTT sensor that you will find on your Overview homepage after you restart the Hassio server.

### Testing your new topic

Let's assume you haven't built the ESP8266 sensor. You can still test your service through the Hassio Developer tools at `http://hassio:8123/dev-service`. Select `mqtt.publish` and just craft a simple payload. Once you call the service you should see the result in the Sensor's component on your Overview