# Tutorial on how to build a Cat Thing (first step)
This tutorial is short and brief overview of my project, called Cat Thing (first step). The initial step is setting up the coding environment and displaying data from a motion sensor, a passive infra-red (PIR) sensor, on a thinger.io dashboard.

### Cat Thing (first step) by ph222zi

Cat Thing (first step) is the initial step in a thing intended for my two cats. They are supposed to have more fun when they are alone at home by having the Cat Thing as their company. The first step does not take long time to do, now that I have figured out the choices for the hardware and the software. I believe it would take less than a day for anyone to copy the work I have done so far on the Cat Thing. A person with programming experience can probably do it from scratch in around one hour. Most of that time will be spent setting up the Arduino (IDE) and getting used to thinger.io and their dashboard designer.

### Objective
The Cat Thing was chosen as my project since I love my two cats and I have been thinking about how to let my cats have more fun when they are alone. I would like to have something that monitors when the cats are active and have some kind of remote interaction with the cats. It could mean activating a rotating toy, dispensing some cat candy, or taking photos of the cats while they play. The activity monitoring could be shown on a dashboard with a time-series diagram. The first step in the project is to use a PIR motion sensor to detect movement and then send the data over WiFi with the TCP protocol. The dashboard is hosted at thinger.io and this data monitoring enables me to see when the cats are active.

### Material
I looked at many different ESP32 boards before I decided that I wanted a board that had built in PIR motion sensor and camera. I found one at [( Link to Swedish HiTechChain´s store )](https://hitechchain.se/iot/ttgo/tgo-t-camera-esp32-wrover-psram-camera-module-esp32-wrover-b-ov2640-camera-module-096-oled) but it was out of stock when I wanted to order it. The price in this Swedish store is 417 SEK including shipping. Instead I started to look around in stores in Europe and I found it in a store in the Netherlands [( Link to the Dutch TinyTronics store )](https://www.tinytronics.nl/shop/en/development-boards/microcontroller-boards/with-wi-fi/lilygo-ttgo-t-camera-esp32-wrover) that was cheaper than the Swedish store, around 272 SEK including shipping.

**Table 1**: *Specifications of the LilyGo TTGO-Camera board version 1.7*.

| Aspect | Specification |
| -------- | -------- |
| Master Chip | ESP32 dual-core |
| CPU Frequency | 240MHz |
| ESP32 Module | Espressif WROVER-B |
| Crystal | 40MHz |
| Protocol | Wi-Fi 802.11 b/g/n & Bluetooth 4.2 BLE |
| Flash | 4MB |
| PSRAM | 8MB |
| Display Chip | SSD1306 I2C |
| Display Type | OLED |
| Display Resolution | 128x64 |
| PIR Motion Sensor | AS312 |
| I2C | Available, but non-standard contact type |
| Uart Chip | CP2104 (programming via micro USB) |
| USB Connector | Micro USB (power & programming) |
| Camera | OV2640 |
| Camera Resolution | 2MegaPixel |
| LiPo Charging Chip | IP5306 (with a built in Boost converter) |

The specifications for the chosen board is shown in Table 1. Note that the micro USB contact is standard but the two white contacts (one on each side of the board) are not of any standard type of JST. It feels like LilyGo has selected these unusual contacts to sell their own cables for this board. The camera uses the majority of the pins. I also liked that the board has two buttons, one for reset and one that can be used for anything.

###### **Figure 1**: *LilyGo TTGO-Camera version 1.7 with ESP32, WiFi, OLED display, two buttons and PIR motion sensor*.

The ESP32 camera board, with a built in PIR motion sensor, is shown in Figure 1. Note that the pin numbers have changed to this in version 1.7 of this board (there are also many similar looking boards that have a different pin layout). A white contact, located on the other side of the board and close to the micro USB connector, has two pins for I2C (called SDA and SCL). The two white contacts on the boards are some variant of JST but I have not been able to find them except for directly from the LilyGo store in China. I am considering removing the two white connectors and solder cables directly to the pads instead. The white connector to the left of the camera is for external power, if one does not want to use the micro USB connector for powering the device.

### Computer setup
Arduino is similar to the C programming language and was chosen because of superior performance (compared to microPython) when sending pictures as fast as possible (to almost get a webcam experience). Both the language and the IDE are called Arduino but I will write Arduino (IDE) for the latter. I added the repository for Espressif ESP32:

`https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`

in the Arduino (IDE) under File - Preferences - Additional Boards manager URLs. The crystal on the board is 40MHz but 80MHz seemed to work good for the compiler setting as well. The settings I use under Tools for the compiler are:


The partition scheme was selected like this because I was experimenting with a code that was over 1MB for the camera to stream pictures over WiFi, and also write debugging messages to the OLED display. The flashing is done via the micro USB contact (the board has a built in UART chip). The default firmware for the board works but it is not recommended as a base for further coding since two libraries are clashing. Instead I recommend the following guide: [( Link to the only working guide I could find for version 1.7 of the board )](https://homeautomation.proboards.com/thread/597/esp32-smart-doorbell-mqtt-camera) and by following this I got the camera and display working but I never managed to combine the code with thinger.io. I settled for adapting code from thinger.io and upload the data from the PIR motion sensor to a dashboard. The library called ThingerESP32.h needs to be installed in the Arduino (IDE).

### Putting everything together
The board is powered via the micro USB connector (5V). It also works with a 5V powerbank until it turns off because the board is using too little current. The PIR motion sensor is built into the board and does not need any extra wires to work.

### Platform
I started with experimenting with MQTT, mosquitto and node-RED but it was hard to get a time-series diagram to work without setting up your own database and web server. I started looking for easier alternatives that also supports showing pictures or mpeg videos. The choice was a free cloud solution (up to two ESP32 devices and 4 dashboards) called thinger.io because I liked the look of their dashboard and the dashboard designer seemed easy to use. Scaling up would be expensive at thinger.io so I would probably have to learn setting up my own database and web server and how to design my own dashboard webpage. The database for storing data in the cloud at thinger.io is called data bucket but I didn't experiment with it yet.

### The code
The repository `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json` and the library called ThingerESP32.h are needed, see the Computer setup section of this text. The code for reading the sensor data and sending it to the dashboard is shown below.

#define THINGER_SERIAL_DEBUG
#define AS312_PIN 33 // ## PIR motion sensor pin number (digital pin)

#include <ThingerESP32.h> // ## ESP32 library for thinger.io
#include "arduino_secrets.h" // ## stores WiFi and thinger.io information

ThingerESP32 thing(USERNAME, DEVICE_ID, DEVICE_CREDENTIAL); // ## arduino_secrets.h


void setup() 
  {
    Serial.begin(115200);
    pinMode(AS312_PIN, INPUT); // ## sets the digital pin as an input for the PIR sensor
    thing.add_wifi(SSID, SSID_PASSWORD); // ## arduino_secrets.h
    thing["millis"] >> outputValue(millis()); // ## milliseconds since the ESP32 booted
    delay(100);
  
    // ## PIR sensor
    thing["PIRsensor"] >> [](pson & out) 
      {
         out["AS312_PIN"] = digitalRead(AS312_PIN);
         Serial.print("PIR sensor (low/high):");
         Serial.println(digitalRead(AS312_PIN));
      };
  }


void loop() 
  {
    thing.handle();
  }

The meaning of >> and pson might not be obvious in this line of the code:

thing["PIRsensor"] >> [](pson & out) 

I will do a short explanation here. PIRsensor will be available in the graphical user interface (GUI) at thinger.io when designing the dashboard for the Cat Thing's data. AS312_PIN, which could have been better named as PIR_sensor_data instead, will be available for the GUI of the dashboard design after selecting PIRsensor in the GUI. The >> assigns pson data type that can hold different data types and is compatible with JSON files. Out just means it is output data. AS312_PIN is actually just a zero (low) or a one (high) depending on if the PIR motion sensor has detected any movement (which results in a high digital signal). [Link to the data passing guide at thinger.io](https://docs.thinger.io/coding/coding-guide#pass-multiple-data).

### Transmitting the data / connectivity
The data is requested by thinger.io once every second. The data is sent over WiFi using the TCP protocol (TCP enables me to use credentials). I also experimented with MQTT, mosquitto, and node-RED but the thinger.io looked much better suited for the continuation of this project. One thing that I especially liked was the thinger.io dashboard designer with support for images and mpeg videos. WiFi and the high polling rate are very bad for the battery consumption but I wanted to test how fast I could get it to update the dashboard. Future work might switch to MQTT, mosquitto and node-RED if I figure out a good way of creating a dashboard that can show images or mpeg video.

### Presenting the data
The data from the PIR motion sensor is presented in a dashboard at thinger.io. The Cat Thing's dashboard is shown in Figure 2. The turquise graph is just the time since the Cat Thing booted up. The orange graph shows 1 when movement is detected and 0 otherwise.

###### **Figure 2**: *Dashboard for the Cat Thing*.

The values are updated once per second and the graphs show the activity during the latest minute. The data is only saved for the latest minute at thinger.io but a data bucket could be used in the future to provide historical data. Cat movement is easiest detected horizontally and vertically, it is harder to get the sensor to react when movement is towards the sensor.

### Finalizing the design
My biggest weakness is the programming part so I am kind of happy with getting this far in the project. There are many ways the project can continue to grow and I will present the plan at the end of this tutorial.

###### **Figure 3**: *Dashboard, Arduino (IDE) and the serial monitor*.

The dashboard, Arduino (IDE) and the serial monitor are shown in Figure 3. Note that the settings for the Arduino compiler are visible in the lower right corner of Figure 3, but are also shown in the Computer setup section. Here ends the description of the current state of the Cat Thing.

### Future work
The plan for the future work is adding pictures or mpeg video for when the motion detector is activated. [Link to a version of the plan that has clickable links](https://lucid.app/lucidspark/d846fd60-9f8d-44d0-b339-1003b4720cd0/edit?viewport_loc=-8%2C-8%2C1768%2C952%2C0_0&invitationId=inv_b8b256ff-1af8-4dfd-9f28-8f62e15f705c#). The idea is to mount the camera on a rotating toy and then stream photos of the cats trying to catch the toy. I should probably add a motor current measurement so I can detect if the cats have caught the toy so I can stop the motor automatically. Activation of the toy is made remotely (in the thinger.io dashboard) or by the motion sensor, after a certain time interval since its last activation. The toy is rotated by a powerful stepper motor, model NEMA 17, and will be controlled by a second ESP32 or via a solid state relay module over I2C (connected to the LilyGo TTGO-Camera board). I haven't made the final decision on whether I should let an ESP32 communicate with a step motor controller or just switch the power to the step motor controller on and off via the relay.

I am considering adding a microphone and speakers to record meows and play sounds, such as purring or greetings, for the cats. I have ordered an inertial measurement unit (IMU) board that is powered by a coin cell battery and sends processed data using Bluetooth. That board could be mounted on or in the toy that is rotating just to get some fun data to display in the dashboard. An overview of the plan for the Cat Thing is shown in Figure 4. The LoRa module is mostly just for experimenting with the Helium network.

###### **Figure 4**: *Overview of the plan for the Cat Thing*.

Only the imagination sets the boundaries for all the fun one can create with some ESP32 boards and too much free time during the summer! I really enjoyed taking an introductory summer course in applied IoT and I am very grateful to the lecturers, teachers, teaching assistants and co-students.