PIOT-CFG-04-001: Install and configure the Sense-Emu Sense HAT emulator for your platform

Description

Install and configure the Sense-Emu Sense HAT emulator and supporting libraries for your platform
- NOTE: These instructions make use of the following open source projects:
- Sense-Emu, located at: Sense-Emu. Reference: The Raspberry Pi Foundation. Sense HAT Emulator. (2016) [Online]. Available: https://sense-emu.readthedocs.io/en/v1.0/.
- Pisense, located at: Pisense. Reference: D. Jones. Pisense. (2016 – 2018) [Online]. Available: https://pisense.readthedocs.io/en/latest/index.html.

Review the README

Please see README.md for further information on, and use of, this content.
License for embedded documentation and source codes: PIOT-DOC-LIC

Estimated effort may vary greatly

The estimated level of effort for this exercise shown in the 'Estimate' section below is a very rough approximation. The actual level of effort may vary greatly depending on your development and test environment, experience with the requisite technologies, and many other factors.

Actions

Dependencies:
- You may need to install and configure GTK and PyGObject for your platform
- See: pygobject docs
Emulator and Library Install:
- Install and configure the Sense-Emu Sense HAT emulator for your platform.
- See: sense-emu docs
- Install and configure the pisense library for your environment.
- See: pisense docs

Windows Notes

I've found that using Windows Subsystem for Linux was helpful for my own Windows 10 install. On Windows 10, I ran a Bash shell, and installed all components as per the Ubuntu guidelines. I then ran all emulator-specific integration tests from another Bash shell command line. On Windows, you'll need an X11 display server.
- Depending on how you install the emulator on your platform (along with GTK), you may need to run the integration test from the command line. For instance, if you use Bash on Ubuntu on Windows, and used the Ubuntu / Debian instructions for installation, you won't be able to run the integration test from within Eclipse, as the libraries won't be installed for the calls to succeed.

macOS Notes

I recently tested the Sense-Emu emulator on a MacBook Pro M3 pro (Apple silicon) running macOS Sonoma 14.1. Using Homebrew (https://brew.sh/), here are the steps I followed:
- NOTES:
- Your system installation needs may vary. Please review the installations instructions at https://sense-emu.readthedocs.io
- My installation was managed via terminal commands
- Python and Pip versions are as follows:
  - Python version: 3.9.6
  - Pip version: 23.3.2
- Install Sense-Emu
- See 'Alternate Platforms' here: https://sense-emu.readthedocs.io/en/v1.1/install.html
- For my macOS system: pip3 install sense-emu
- Install PyGObject libs
- brew install pygobject3 gtk+3
- Make sure your Python install is available in your PATH
- I added $HOME/Library/Python3.9/bin to the PATH in my $HOME/.zshrc file
- Re-source your .zshrc or open a new terminal after the PATH update
- Install PyGObject for Python
- pip3 install pygobject
- Test the Sense-Emu GUI
- sense_emu_gui

Pisense v0.2 Notes

Depending on your local version of Pillow and other library dependencies, you may experience some Python version deprecation warnings or errors when using pisense within the CDA. This may be the case specifically with Pisense 0.2 and Python 3.10.
- NOTE: If you don't see the error below, and the SenseHatEmulatorQuickTest runs without any issues, you can ignore the following.
- Here's some sample log output that reflects this error when running SenseHatEmulatorQuickTest:

======================================================================
ERROR: testCheckEmulator (SenseHatEmulatorQuickTest.SenseHatEmulatorQuickTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/mnt/d/piot/piot-cda-solutions/src/test/python/programmingtheiot/part02/integration/emulated/SenseHatEmulatorQuickTest.py", line 53, in testCheckEmulator
    self.sh.screen.scroll_text(self.HELLO_WORLD_A)
  File "/mnt/d/piot/piot-wsl-venv/lib/python3.10/site-packages/pisense/screen.py", line 469, in scroll_text
    frames = [image_to_rgb565(frame) for frame in frames]
  File "/mnt/d/piot/piot-wsl-venv/lib/python3.10/site-packages/pisense/screen.py", line 469, in <listcomp>
    frames = [image_to_rgb565(frame) for frame in frames]
  File "/mnt/d/piot/piot-wsl-venv/lib/python3.10/site-packages/pisense/anim.py", line 219, in scroll_text
    img = draw_text(text, font, size, foreground, background,
  File "/mnt/d/piot/piot-wsl-venv/lib/python3.10/site-packages/pisense/anim.py", line 168, in draw_text
    width, height = draw.textlength(text, f, spacing=1)
TypeError: ImageDraw.textlength() got an unexpected keyword argument 'spacing'

From what I understand, the ImageDraw library in 3.10 has deprecated the textsize function, although in my own testing, it appears you can use textbbox instead. Since the version of pisense I tested with relies on textsize, there are at least two potential ways to address this issue.
- (1) You can either downgrade your Python (and Pillow) implementation (not recommended due to a CVE concern - see https://pillow.readthedocs.io/en/stable/releasenotes/10.0.1.html), or
- (2) make a minor adjustment to the pisense anim.py module's source code, as shown below.
How to update pisense anim.py source code module:
- In the pisense module anim.py, you can change line 167 as follows (you'll find this under {your python install location}/lib/python3.10/site-packages/pisense/anim.py):
```
line     code
-----   -----
167:   #width, height = draw.textsize(text, f, spacing=1)
168:    x, y, width, height = draw.textbbox((0,0), text, f)
```

Estimate

Small

Tests

NOTE: Depending on how you install the emulator on your platform (along with GTK), you may need to run the EDA integration tests from the command line vs from within your IDE.

For instance, if you use Bash on Ubuntu on Windows, and used the Ubuntu / Debian instructions for installation, you may have difficulty running the EDA integration tests from within Eclipse, as the libraries won't be installed for the calls to succeed. On Windows 11 with Visual Studio Code (VS Code), assuming WSL v2 is configured properly and VS Code is launched from WSL, you should be able to run VS Code in WSL mode and invoke the test from within WSL directly from the IDE.
Setup
- Linux
- NOTE 1: If you're using Windows 10 and WSL (based on Ubuntu), you'll need an actively running X11 server.
- NOTE 2: If you're using Windows 11 and WSL 2 (based on Ubuntu), you should not need a separate X11 server, as Windows 11 and WSL 2 should support rendering of X11-baseed UI's automatically.
- Open a terminal and execute the following:
```
export DISPLAY=:0
sense_emu_gui
```
- The Sense-Emu emulator GUI should launch depicting a UI that looks similar to the Sense HAT

Integration tests (in ./src/test/python/programmingtheiot/part02/integration)

Run the unit test cases in ./emulated/SenseHatEmulatorQuickTest. All tests should pass.

cd ./src/test/python/programmingtheiot/part02/integration/emulated
python -m unittest SenseHatEmulatorQuickTest

The Sense-Emu GUI should scroll three messages across the screen in sequence:
A 'hello world' message.
A 'welcome' message.
A 'temperature is' message.

Command line output from the integration test will look similar to the following:


2020-09-06 21:44:54,331:SenseHatEmulatorQuickTest:INFO:Testing SenseHatEmulatorQuickTest class [using SenseHAT emulator]...
2020-09-06 21:44:54,354:PngImagePlugin:DEBUG:STREAM b'IHDR' 16 13
2020-09-06 21:44:54,355:PngImagePlugin:DEBUG:STREAM b'IDAT' 41 367
2020-09-06 21:44:54,356:Image:DEBUG:Error closing: 'NoneType' object has no attribute 'close'
.
----------------------------------------------------------------------
Ran 1 test in 33.707s

programming-the-iot / book-exercise-tasks

PIOT-CFG-04-001: Install and configure the Sense-Emu Sense HAT emulator for your platform #50