Skip to content

Latest commit

 

History

History
368 lines (270 loc) · 12.2 KB

machinon_install_guide.md

File metadata and controls

368 lines (270 loc) · 12.2 KB

Installing Machinon (I) - Main setup

  • This guide covers the main Machinon setup, which is mandatory and provides all the functionality to use your Machinon in a local network environment.

Install Raspbian

NOOBS is a very simple way to create a bootable Raspbian linux SD card from any OS (windows, osx, etc...) as it only implies downloading a zip file and unzipping it into a fresh formatted SD card. However, if you plan to clone your SD card after you finish this installation (using dd or any other SD cloning software), to use it into multiple Raspberries, creating a traditional Raspbian image SD card is recommended.

Using Noobs

  1. Download NOOBS installer from https://www.raspberrypi.org/downloads/noobs/
  2. Formatting SD Card in fat32 with SDFormatter (Mac) or Windows similar tool.
  3. Unzip NOOBS zip file into SD card. Ensure the SD card's root folder shows a bunch of files. If the root folder contains only a NOOBS folder, you've done wrong. Check the INSTRUCTIONS-README.txt file inside the NOOBS folder for detailed explanation.
  4. Eject SD card safely, put it into Raspberry, attach keyboard, network cable, monitor, etc... and boot.
  5. A very easy installation wizard will appear, choose to install Raspbian Lite and follow instructions. You may need to configure your WiFi if not using cabled networking with DHCP.
  6. The installation takes some minutes depending of your network connection.

Using Raspbian Image

This method is preferred for headless installs (no keyboard or screen) with the Pi mounted in a Machinon unit.

  1. Download the Raspbian Stretch Lite OS .zip image from the Raspbian site: https://www.raspberrypi.org/downloads/raspbian/
  2. "Burn" the image onto a microSD card (min 4 GB size) using one of the various tools available. For OSX and Windows you can use balenaEtcher (reads .iso, .img and .zip images). On Windows, you can use Win32DiskImager (.img only), Rufus (.img and .zip) and others.
  3. After the image is written, open the card's boot partition and create an empty file named ssh (no file extension). This will enable SSH access to the Pi.
  4. Eject SD card safely, put it into Raspberry Pi (either bare Pi or mounted in a Machinon unit), attach network cable and power it up. You can then find the Pi's IP address and log in using any SSH client.

Post installation setup:

Once rebooted and the screen shows the classic linux login. Use username pi with password raspberry to login.

Run the Raspbian configuration tool

sudo raspi-config
  1. Update raspi-config tool (8th option)
  2. Set new password for user 'pi', chose anything you want.
  3. Network options :
  • N1 - Set hostname to something like machinonNN where NN is a number.
  • N3 - Do not enable predictable network interface names.
  • N2 - You can enable WiFi and connect to internet through it**

** agent-machinon uses the eth0 interface MAC Address as Re:Machinon's MUID (Machinon Unit ID). So, even if you are using WiFI to access internet with the Raspberry, don't disable eth0 interface.

  1. Boot options :
  • Boot on console (WITHOUT autologin)
  1. Localization options :
  • Timezone
    • Choose "None of the above", then UTC
  • Locales
    • Usually choosing EN_GB@UTC-8 is fine. Raspbian detects your location so, if you use another locale, install it to avoid Raspbian dropping Locale error messages.
  • WiFi Country
    • Set your country here if you want to use WiFi.
  1. Interfacing options (based on Matthew's instructions)
  • Enable SPI
  • Enable I2C
  • Enable Serial
    • Do NOT enable login shell over serial.
  • Enable remote command line through SSH (if not already done via the ssh file in the boot partition).
    • Not required but it allows to do the rest of the setup through SSH, so you can detach the Raspberry from monitor/keyboard/etc...
  1. Advanced options :
  • Expand filesystem to fill card.
    • If you installed Raspbian using NOOBS this step is not required.
    • Latest Raspbian image also performs this procedure during the first boot.
  • Change GPU memory to 16 MB

The program will ask you to reboot. Select "Yes"

Updating the OS

Log in to the Pi again, and update the operating system. Answer yes (Y) if the commands ask for confirmation.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade
sudo apt-get clean

Network address setup

At this stage, your Pi probably already has a dynamic IP assigned by DHCP. To find this IP run:

ip route get 1 | awk '{print $NF;exit}'

And note down the IP address. You'll need it to open the web server pages later.

Through this document we will use 192.168.1.15 as a sample IP address. The actual address may be different on your device, though.

== OPTIONAL == Setting a static IP address

Optionally you can set an static IP address. Doing this step implies you know your network settings. Assigning a wrong IP address could leave your Raspberry inaccessable!

sudo nano /etc/dhcpcd.conf

Uncomment or add the following lines, using suitable IP settings for your network. As an example we are using a 192.168.1.x network range, but you must choose an IP that suits your network settings:

interface eth0
static ip_address=192.168.1.15/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1

Reboot to apply the network changes

sudo reboot

Accessing your Raspberry through SSH

You can access your Raspberry through SSH instead of having it attached to a monitor, keyboard, etc. This is the normal method of accessing the Pi when it is mounted into a Machinon system.

Adding system overlays to boot config

sudo nano /boot/config.txt

Add the following lines. enable_uart is probably already enabled in the file due to the raspi-config setup

# Enable UART Pi3 and Jessie or later
enable_uart=1
# Enable SC16IS75x SPI-UART expander
dtoverlay=sc16is752-spi1,24
# Enable Machinon RTC
dtoverlay=i2c-rtc,mcp7941x
# Redirect SD/Activity LED to Machinon front panel
dtoverlay=pi3-act-led,gpio=26
# Change BT to mini-uart (Pi3 only)
dtoverlay=pi3-miniuart-bt
# Optionally disable wifi
dtoverlay=pi3-disable-wifi
# Optionally disable bluetooth
dtoverlay=pi3-disable-bt

Disable bluetooth service from starting

This prevents service startup errors:

sudo systemctl disable hciuart

Allow applications to use serial port

sudo nano /boot/cmdline.txt

Remove the text console=serial0,115200 if it appears in the command line. See https://www.raspberrypi.org/documentation/configuration/uart.md for more info.

Adding modules

sudo nano /etc/modules

Add a new line with rtc-mcp7941x then save and exit.

Setting hardware clock

sudo nano /lib/udev/hwclock-set

Comment out (add # to start of lines) the following lines:

if [ -e /run/systemd/system ] ; then
    exit 0
fi

Reboot to apply all previous changes

sudo reboot

Check that the Pi has correct time from network with date (keep in mind we are using UTC time zone).

Optionally manually set HW clock with sudo hwclock -w to write system time to HW clock. The Pi will automatically load the time/date from the HW clock at boot, and update the HW clock from NTP when it is available. You can also use sudo hwclock -s to manually set the system clock from the HW clock.

The Pi does an NTP update of system clock at boot, and periodically thereafter, and sets the RTC from this.

Aliasing serial ports nodes

Add a permanent alias for the RS485 SPI UART (Domoticz does not show port names like "ttySC0", so here we create an alias to "serial485" for the RS485 port).

sudo nano /etc/udev/rules.d/98-minibms.rules

Put the following content on the file

KERNEL=="ttySC0" SYMLINK="serial485"

Reboot and after that check ls -l /dev command to ensure serial485 appears in the results as an alias for the ttySC0 port.

Create Machinon's main folder

This folder will contain all our applications related to Machinon

sudo mkdir -p /opt/machinon/scripts
sudo chown pi:pi -R /opt/machinon

Install Domoticz

curl -L install.domoticz.com | sudo bash

An install wizard will run after a few minutes:

  • Enable both HTTP and HTTPS access
  • Set HTTP port 8080
  • Set HTTPS port 4443
  • Set installation folder into /opt/domoticz

Domoticz is installed as a service, to control it you can run the usual systemctl commands.

sudo service domoticz.sh start|stop|restart|status|etc...

In case of errors you can run Domoticz from command line for testing and interactive output:

cd /opt/domoticz
./domoticz

==OPTIONAL== : Showing your IP in the Machinon's LCD screen

This will help you quickly know the current IP on your Machinon.

sudo nano /opt/machinon/scripts/get-ip.sh

Copy/clone the file get-ip.sh script from Machinon Github on the the following code on the file. Save, exit and apply permissions.

sudo chown pi:pi /opt/machinon/scripts/get-ip.sh
sudo chmod 755 /opt/machinon/scripts/get-ip.sh

After that you'll have to add a dzVents script on Domoticz (we will continue this procedure later...)

==OPTIONAL== : Add Hardware on Domoticz

Open a browser and access http://192.168.1.15:8080/

Change the IP in this URLS to match your network configuration.

The Domoticz screen should appear.

  1. Add a new "MySensors USB Gateway" hardware under "Hardware" menu
    1. Name the hardware "Machinon_IO" or similar
    2. Select Serial port serial0 and baud rate 115200
  2. Copy/clone the presentation.sh script from Machinon Github to /opt/machinon/scripts and run it to present the Machinon I/O devices to Domoticz. This tells Domoticz the I/O channel names, firmware versions etc. Refresh the Domoticz hardware list and click "Setup" on the Machinon_IO hardware entry to see the names, or view the Devices list.

Install Nginx + PHP

This covers all requirements for machinon_config and machinon_client packages.

sudo apt-get -y install nginx php-cli php-common php-fpm php-cgi php-pear php-mcrypt php-curl memcached ssl-cert

Install machinon_config

Create nginx server block (a.k.a. virtual host)

cd /etc/nginx/sites-available
sudo nano machinon.conf

Add the following config in that file:

# Machinon Config server block
server {
    listen 80 default_server;
    root /opt/machinon/config/public;
    index index.html index.htm index.php;
    server_name _;
    location = /machinon {
        rewrite ^ machinon/ redirect;
    }
    location /machinon/{
        proxy_pass http://localhost:8080/;
    }
    location = /machinon/backupdatabase.php {
        proxy_pass http://localhost:8080/backupdatabase.php;
    }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
    }
    location ~ /\.ht {
        deny all;
    }
    location ~\.sh$ {
        deny all;
    }
}

Enable the server block and reload config (or start server):

cd /etc/nginx/sites-enabled
sudo rm -f default
sudo ln -s ../sites-available/machinon.conf machinon.conf

If using ‘Buster’ then php is updated from 7.0 to 7.3, so the following line in machinon.conf;

    fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;

Must be changed into;

    fastcgi_pass unix:/var/run/php/php7.3-fpm.sock;

Setting serial port permissions for nginx

Set user/group permissions to allow NGINX group/user www-data to access the serial port:

sudo usermod -a -G dialout www-data
sudo usermod -a -G www-data pi

Download machinon_config

cd /opt/machinon
sudo git clone https://github.com/EdddieN/machinon_config config
sudo chown pi:pi -R config

Register the Nginx service and restart it.

sudo systemctl enable nginx
sudo service nginx restart

You can now access the Machinon's hardware config app by browsing to http://192.168.1.15/

To open the Domoticz app directly, go to http://192.168.1.15/machinon/

Change the IP in these URLS to match your network configuration.

At this point, your Machinon setup is completed for a local network environment.

Accesing your Machinon device from outside of your network

If you want to access remotely your Machinon devices through our Re:Machinon portal read this guide.