AdoPiSoft Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**Version 4.0.0**


====== Installation ======
There are two ways you can install AdoPiSoft System into your machine:
  - **[[4.0.0:index#1._image_flashing| Image Flashing (Orange Pi, Raspberry Pi, Newifi)]]**
  - **[[4.0.0:index#2._command-line| Command Line (Ubuntu Server 16.04/18.04 or Armbian)]]**


===== 1. Image Flashing =====
Image flashing is the easiest way to install the system into your machine (if an image is available for your board/machine).

Softwares to Download:
  - Download [[ https://etcher.io/ | Etcher]]
  - Download the [[4.0.0:software_image | Software Image]] appropriate for your board/machine.

After downloading the needed softwares, we need to flash the image into the midro SD card using **Etcher**. To do so, unzip the contents of the zip file **(adopisoft-xxxxx.zip)**.

Insert the micro SD card into the your computer using a card reader.

Open **Etcher** and click **Select Image**. {{ :4.0.0-beta.1:etcher-select-image.jpg?600 |}}

Then select **adopisoft-(version).img** from the zip file. {{ :4.0.0-beta.1:select-adopisowifi-img.png?600 |}}

Make sure to select your micro SD card {{ :4.0.0-beta.1:select-usb-drive.png?600 |}}

Click the **Flash** button and wait for the process to finish.

**NOTE:**
If you encounter prompts about formatting your sd card, just click **Cancel**.

Now, you are ready to configure the machine. Eject the SD card and Proceed to [[4.0.0:index#initial_setup| Initial Setup]] section.


===== 2. Command-Line =====
**Important:** Before proceeding with command-line installation, it is assumed that you are already familiar on how to install a debian-based operating system into your board/machine.


Command line installation is used when software image is not available for your board/machine. First, you need to have access to the command line of your board/machine. In this guide, we will use **Raspbian** as an example. But this guide is also applicable to any debian-based OS like [[https://www.armbian.com/download/ | Armbian ]] and [[https://ubuntu.com/download/server | Ubuntu Server]] 16.04/18.04 . For Orange PI boards, you can download the [[http://www.orangepi.org/downloadresources | OPI image here]]. Just follow the corresponding board type and their supported OS.

**NOTE:**
//Make sure to install a command-line OS only. OS's with desktop environment is not supported. For Raspberry Pi, this means the Raspbian Lite image. For Ubuntu, choose the Ubuntu Server ISO(16.04/18.04). Armbian is almost always command-line only.//

Connect your **LAN cable**, **keyboard**, **monitor** and **USB to LAN adapter**(optional) to your board. Then power on your board and wait for the login screen to appear.  The default user for Raspbian is **pi** with password **raspberry**.

**For armbian:** After logging in, you will then be asked to create a new user. Just follow the instructions on your device's screen. After creating a new user, you are now ready to install the system into your board/machine.

Just copy-paste the commands below line by line:
  sudo apt-get update && sudo apt-get upgrade -y
  sudo apt-get install curl -y
  curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
  sudo apt-get install -y nodejs python nginx bind9 isc-dhcp-server
  sudo apt-get install -y hostapd dmidecode build-essential openssh-server python-pip unzip bridge-utils
  
This is for Orange Pi only:
  sudo pip install --upgrade OPi.GPIO

**Note:** You can find your board's architecture using:
  dpkg --print-architecture
  
For Raspberry Pi 3 & 4, OrangePi Zero/One/PC (armhf architecture):
  wget https://github.com/AdoPiSoft/Releases/releases/download/4.1.2/adopisoft-4.1.2-release-armhf-node-v12.16.1.deb
  sudo apt-get install ./adopisoft-4.1.2-release-armhf-node-v12.16.1.deb


For x64 machines - VM's/Server (amd64 architecture):
  wget https://github.com/AdoPiSoft/Releases/releases/download/4.1.2/adopisoft-4.1.2-release-amd64-node-v12.18.3.deb
  sudo apt-get install ./adopisoft-4.1.2-release-amd64-node-v12.18.3.deb
  
For RaspberryPi, you have to unblock wifi:
  sudo rfkill unblock 0

  
Make sure to disable SSH service after a successful installation. **Warning:** You will not be able to access your board/machine command-line **remotely** after this.

  sudo systemctl disable ssh

Now, **enable and start adopisoft service** and proceed to [[4.0.0:index#initial_setup| Initial Setup ]] section.

  sudo systemctl enable adopisoft
  sudo systemctl start adopisoft


  
**Note:** The default database used is **sqlite** because it's the only database that can be package into the debian file. But we highly advice to change the database to postgresql after you have successfully setup the admin.

Run the command below line by line to create postgresql account:

(//if the script will not work you can follow the [[https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-18-04 | step by step guide here]]//)

  wget https://gist.githubusercontent.com/alenteria/791dbe32175a01d1f1b602b25489ad22/raw/9a5aa879ac70d24bd9a7dd7f8ed97d7fe2c2f597/ado-psql-script.sh 
  
  sudo chmod a+x ./ado-psql-script.sh
  sudo ./ado-psql-script.sh
  --- if the above command failed, try the following: ---
  bash ./ado-psql-script.sh

Then in the admin "Security -> Database Connection" settings, change the config to:

  Database Type: postgres
  Host/IP: localhost
  Port Number:
  Database Name: adopisoft
  Username: adopisoft
  Password: adopisoft

Restart machine and go back to "Security -> Data Connection" after boot and click "Run migrations".
====== Initial Setup ======

**IMPORTANT**: Make sure you do the following before turning on your board/machine:

  * Insert the SD card into the board's SD card slot.
  * Insert the LAN cable into the ethernet port of board/machine and make sure it is connected to internet
  * Insert USB to LAN adapter (if your board doesn't have wifi interface).

Find your board/machine's IP address. In your board/machine's screen, just type:

<code>ip addr</code>

On windows, you can install [[https://www.advanced-ip-scanner.com | network scanner ]] on your PC to scan for your board/machine's IP.

Once you have identified your board/machine's IP address, open your browser on your PC and type the url to your board/machine's IP address.

Example: 

  http://192.168.1.123
  
===== Installation Wizard =====
  
==== Setup Account ====
  - Type your password
  - Confirm your password
  - Click **Save Changes** button

==== Select Board ====
  - Choose your board/machine type
  - Click **Save Changes**

==== Setup WAN ====
  - Select your WAN network interface. The system will automatically recommend the interface connected to your network.
  - Click **Set as WAN Interface** button
  - Configure your WAN interface (Dynamic IP or Static IP). If not sure, check **Obtain IP from DHCP server**.
  - Click **Save Changes** button

==== Setup LAN ====
**Important:** Make sure your board/machine has two network interface. For boards without wifi interface, you have to insert the USB to LAN adapter first.

  - Choose the network interface for your LAN. It can be the wifi interface (wlan0 or wlpsxxx) or any ethernet interface.
  - Check **Enable Captive Portal**
  - Set alias to **LAN Interface** or **Built-in WiFi** //(or anything you like)//
  - Uncheck **Obtain IP from DCHP server**
  - Set Statc IP Address to **10.0.0.1**
  - Set Network Prefix to **20**
  - Check **Use System DNS Server**
  - Check **Enable DHCP Server on this interface**
  - Set DHCP Pool Start to **10.0.0.10**
  - Set DHCP Pool End to **10.0.15.254**
  - Click **Save Changes** button
  - Click **Done** or **Finish** button.

==== Setup WiFi ====
**NOTE:**
//This is only applicable for boards/machine with built-in wifi interface like Raspberry Pi.//

  - Check **Enable Built-in WiFi**
  - Set **WiFi Name** to your preference
  - Check **Open WiFi**
  - Check **Don't limit the number of users**
  - Set LAN Interface to **wlan0** //(or whatever the name of your wifi interface)//
  - Select channel to your preferrence //(default 1)//
  - Click **Save Changes** button

==== Reboot ====
Reboot your machine. Then proceed to [[4.0.0:index#built-in_wired| Wired Coinslot Configuration]] section.


====== Dashboard ======

===== System Status =====

Contains details about CPU, RAM, storage, network interfaces and network traffic.

{{:screenshot_from_2020-02-19_13-27-23.png?direct&600|}}

----

===== Announcements =====
Contains announcements fetched from our server. Contents of this page can also be viewed at [[https://www.adopisoft.com | website home page]].

----

===== WiFi Users =====

==== WiFi Users List ====
In wifi users list, you can view the devices connected to wifi which includes the **hostname, mac address, ip address** and **status** of individual device.

{{ :wifi-users.png?direct&600 |}}

For each device, you have the options to **view sessions, edit** and **block or unblock** the device.


==== WiFi User Sessions ====


You can view the sessions for each individual device.

{{ :wifi-user-sessions.png?direct&600 |}}

You can **add/edit/remove** individual sessions. Please see [[4.0.0:index#session_types| Session Types]] for more information about session types.

{{ :edit-session.png?direct&600 |}}


==== Edit Device ====

Edit device details like hostname, mac address and ip address.

{{ :edit-device.png?direct&600 |}}

===== Payment Portals =====
==== Built-In / Wired ====
Built-in coinslot uses on-board GPIO pins as sensor for coin acceptors.

=== Configuration ===
  - Click **Add Wired Coinslot** button
  - Select **GPIO** coinslot type
  - Set alias //(ex. Frontyard Coin Slot)//
  - Set **GPIO Pin for Coin Acceptor** to **3** (or any [[4.0.0:gpio_numbering| GPIO pin ]] you prefer)
  - Set **GPIO Pin for Bill Acceptor** //(if you have bill acceptor)//
  - Set the relay settings if you have a relay setup for inhibit pin //(opotional)//. Please refer to [[4.0.0-beta.1:relay_setup]] for more information.

=== Wiring Diagram (RPI) ===
Click on the image below to view full size.
{{ :4.0.0-beta.1:circuit-diagram.jpg?direct&600 |}}

=== Wiring Diagram (OPi One & PC) ===

{{:4.0.0-beta.1:opi_one_gpio_diagram.jpeg?direct&600 |}}


=== GPIO Numbering ===
Please refer to [[4.0.0:gpio_numbering]] page.

==== Serial Coinslot ====
Serial coinslot uses Arduino to handle credit pulses, lcd display, and keypad E-loading. The data is transmitted via USB serial.

=== Flash Arduino ===
2 ways to flash arduino
  - **[[:arduino_serial_flashing_using_phone| Using Android Phone with OTG support]]**
  - **[[:arduino_serial_flashing_using_pc| Using PC]]**

=== Configuration ===
  - Click **+ Add Wired Coinslot** button
  - Select **Serial** coinslot type
  - Set alias //(ex. Frontyard Coin Slot)//
  - Set Serial Device port //(usually __/dev/ttyUSB0__)//
  - Set Serial Baud Rate to **9600**
  - If your setup has lcd module, click **Show LCD Display Settings** and tick the menu you want to appear in the LCD.
  - If you tick the **Enable Hotspot menu**, **WiFi SSID** field will show. This will reflect in the LCD display that will serve as an instruction to customers on which SSID they should connect.
  - Connect your Arduino to the machine via USB and restart to apply changes.


=== Wiring Diagram ===

Materials Needed:
  - Arduino Uno or any arduino with equal or higher memory capacity than uno
  - Universal Coin Acceptor
  - 4×3 Membrane Keypad Module (//Optional, only if E-loading is enabled//)
  - ST7920 128x64 LCD Display Module (//Optional//)
  - Bill Acceptor (//Optional//)


{{ :4.0.0-beta.1:ado-serial.pdf | Download Diagram}}
{{ :4.0.0-beta.1:ado-serial-1.png?direct |}}


==== Wireless Coinslot ====
Wireless coinslot uses ESP8266 board as coinslot sensor. You can also connect LCD and keypad to the ESP8266 board for E-loading setup. The ESP8266 will automatically connect to the machine given that it has the correct ssid config and has matching token or encryption key. Connected ESP8266 devices will show in the **CONNECTED WIRELESS COINSLOTS
** table. Click on the **edit** or **pencil** icon on the device to show the LCD menu settings.

=== Configuration ===
  - Set **SECURITY TOKEN** //(This should match with the ESP8266's token)//
  - Flash your ESP8266 board. Please refer to [[4.0.0:wireless_coinslot_flashing| ESP8266 Flashing guide]] for more information.
  - Configure your ESP8266. Please refer to [[:esp8266_configuration_guide| ESP8266 Config guide]] for more information.



=== Basic Diagram ===
Materials needed:
  - NodeMCU or WEMOS
  - Universal Coin Acceptor

{{ :4.0.0-beta.1:ado-wireless-basic.pdf | Download Diagram}}
{{ :4.0.0-beta.1:ado-wireless-basic.png?direct& |}}

=== Wiring Diagram With Keypad E-loading ===
Materials needed:
  - NodeMCU or WEMOS
  - Universal Coin Acceptor
  - Arduino Uno or Nano
  - 4×3 Membrane Keypad Module
  - ST7920 128×64 LCD Display Module
  - Bill Acceptor

{{ :4.0.0-beta.1:ado-wireless.pdf | Download Diagram}}
{{ :4.0.0-beta.1:ado-wireless.png?direct& |}}


**Important Note**: All the modules should be in common grounds, or use common power adapter.
For bill acceptor, don't directly connect the inhibit wire into the ESP8266 as it can damage your board. Use a relay to ON and Off the ground connection to the inhibit.


**PIN D8** can be use for **Buzzer** or for **Physical Reset button** (use the correct binary file, suffix with D8-reset or D8-buzzer).

For a **Reset Button**, connect to 3V on button press. When pin D8 is HIGH, payment que session will be cancelled same as clicking "Cancel" on the captive portal payment que.

For a **Buzzer**, it usually has 3 wires 2 for power(+/-) and 1 for input which is PIN D8. Please refer to [[4.0.0:buzzer-module| Buzzer module guide]]

----

====== Terminologies ======

===== Session Types =====


There are 3 main types of sessions in our system available in captive portal:

==== 1. Time Session ====
This is the traditional session with remaining time in seconds. But unlike before, each transaction has separate time. They are not combined to previous session. The session becomes invalid once the user has consumed the allocated time.

==== 2. Data Session ====
This session is based on data consumption of the user. The session becomes invalid once the user consumed the allocated data in megabytes (MB).

==== 3. Time or Data Session ====
Whichever is consumed first, time or data. The session will become invalid once either of time or data is consumed by the user.

The user can have multiple sessions, including the subscription session. Once the previous session is consumed, it will automatically activate the next available session. If the user has no more sessions available, the user is automatically disconnected from the internet.

==== Subscription Session ====
The other type of session is **Subscription**. Subscription session does not have allocated time or data. Instead, it will only track the data consumption of the device and how long the session has been running. Subscription session can only be generated manually in the dashboard for the intended device or through voucher. It can be used to allow only specific hosts to connect outside the network - e.g. smart TV’s, CCTV/IP Cameras, etc. aside from walled-garden based on TCP/IP port numbers. It can also be used to accommodate a whole household using a voucher with subscription type session.

Each session is editable and has the following options:

  * Download/Upload Bandwidth Limit
  * Allow/Disable Pause
  * Expiration Date/Time
  * Change Session Type (options: time, data, time or data, subscription)
  * Add/Subtract remaining time or data
  * Delete session

The default bandwidth of a session is taken from captive portal bandwidth settings.
The default session expiration is taken from session settings in the admin dashboard. The expiration date/time can be disabled.
AdoPiSoft Wiki

User Tools

Site Tools

Page Tools
