Integrating serial GSM Modem with Home Assistant

This is how to enable Home Assistant’s SMS Integration Service using the Geetech Arduino GPRS Shield (based on the SIMCom SIM900 module) on a Raspberry PI 4 over serial communication. The host system is using Home Assistant Supervised which was deployed in docker.

Unlike previous versions of Raspberry PI, Raspi 4 has a total of 6 Serial Ports (UART0 to UART5). By default UART0 (ttyAMA0) drives the bluetooth chip and UART1 (ttyS0), when enabled, is being used for the Serial Console. Building on top of this, by editing the /boot/config.txt file and appending the following lines:

enable_uart=1
dtoverlay=uart2

the Serial Console will be enabled, and the UART2 will be available for our GSM Shield.

Hardware connections

Enable Serial Console by connecting a Serial’s cable RX signal to Raspi’s TX (GPIO 14) and the TX to Raspi’s RX (GPIO 15). This is an optional step, but give us a redundant way of communication with the Raspberry PI.
To connect the Serial GSM Shield, a Bi-Directional Logic Level Shifter is required, due to the fact that the Shield is using 5V logic while RPI uses 3.3V logic. At first, connect Shield’s Hardware RX and TX pins to Logic Level’s Shifter B1 and B2. Next, Connect Raspi’s UART2 TX (GPIO 0) and RX (GPIO 1) to Logic Level’s Shifter A1 and A2. Finally connect Shield’s Ground and 5V pins to Logic Level’s Shifter Ground and HV pins, and Raspberry Pi’s Ground and 3.3V pins to Logic Level’s Shifter Ground and LV pins.

Shield’s Configuration

1. Use a SIM Card with disabled PIN and make sure that is working before using it in the Shield.
2. Set the Serial Jumper’s to the Hardware side (Xduino).
3. Set the power switch to "Arduino" and provide power through the pins as shown in the above diagram. If you prefer to use the power jack you can do it but don’t forget to provide 5v power to the Logic Level Shifter (the 5v pin on the shield’s header is not connected to the power jack).
4. Pay special attention to the power needs of the Shield. It CANNOT be powered from the Raspberry PI, you must use an external power supply.

Test Serial Console [optional]

Reboot your Raspberry PI, and using a Serial connection to your computer, wait for the Serial Console to load using Putty or any similar software. Try to login using your credentials, everything must be similar to an SSH Session to the Raspberry PI.

Test Shield’s Connectivity

To check Shield’s connectivity, install Minicom on Raspberry, using the following command:

sudo apt install minicom

and then run it specifying the serial device and the baud rate (19200):

minicom -b 19200 -D /dev/ttyAMA1

Power on your GSM shield (holding down the power button for about 2 seconds) and wait until the following messages appear on the screen:

Those messages are a confirmation that everything is ready for the Home Assistant integration. To exit from Minicom press CTRL + A, followed by X, and to the popup window, confirm that you want to quit.

Configuring Home Assistant SMS Integration

Before enabling the SMS Integration two configuration files of the Home Assistant must be modified. The reason is that, this integration is based on Gammu project but the only available property for configuration through Home Assistant is the "device". The "connection" variable which is also important is hard-coded as "at". As is stated in Gammu’s manual for devices without automatic configuration of the baud rate, the connection string can be modified with the rate following the "at" command.
So at first, edit the file /usr/src/homeassistant/homeassistant/components/sms/__init__.py file and at line 42 replace at with at19200. The new line must look like:

config = {"Device": device, "Connection": "at19200"}

Next, edit the file /usr/src/homeassistant/homeassistant/components/sms/config_flow.py and at line 24 replace again, at with at19200. As before the final result must be:

config = {"Device": device, "Connection": "at19200"}

After that, you are ready to make the integration following the SMS Integration guide. Edit your Home Assistant’s configuration.yaml and add the following lines:

# Example configuration.yaml entry
sms:
  device: /dev/ttyAMA1
notify:
  - platform: sms
    name: sms_person1
    recipient: PHONE_NUMBER

and restart your Home Assistant Server (Coniguration->Settings->Restart)

Test SMS Integration

Following the restart, a new notification with "New devices discovered" title will appear, and no errors must be shown in Configuration->Settings->Logs.
Also in the Configuration->Devices & Services a new Integration must appeared, with the IMEI Number as title and 1 device and 1 entity.

If all of the above are as described, then from Developer Tools->Services, Select as a Service the notify.sms_person1 (the same as the one you used in the configuration file), type a message and click Call Service. Your message must arrived at the phone number you specified in the configuration file.