Programming the VMC
[[TOC]]
Vendiverse is an open-source vending machine controller project. This project provides both hardware and software in an open-source manner so that anyone can change both hardware and software to meet its requirements.
If you have completed steps in Making a Vendiverse VMC Board or if you have obtained a Vendiverse VMC board, you can start programming Vendiverse VMC Board.
Orange PI Zero is the brain of Vendiverse VMC Board. It is a SoC mikro-pc with 256/512 MB of RAM, 1.2 GHz Quad Core H2+ based CPU, Micro-SD card support of up to 64 Gigabytes. It has several low speed interfaces such as I2C, UART, SPI and GPIO. This single board computer is a the perfect choice for controlling a vending machine.
OPZ can run Linux operating system. There is a special distribution that is tailored for Orange PI boards named Armbian. You can download an image of Armbian, burn image on a Micro-SD card and insert it into OPZ and quickly start working. Additionally, you need to install MySQL / Maria DB, Python, some low level Python libraries for SPI, I2C and Serial communication.
If you are not a Linux geek, you can download Vendiverse Armbian Image, which contains all necessary software and libraries pre-installed.
If you want to install all libraries required for Vendiverse by yourself, you can download Armbian OPZ Image.
Armbian OPZ Image (Debian Jessie Flavor)
If you don't want to spend time creating Linux environment for Vendiverse and quickly start using it, download the image below.
Vendiverse Armbian Image Download
Once you have downloaded and extracted the content of archive file (it may be 7z or Rar file), you will have a file with a .img extension.
Image files can not be simply copied to micro-sd card. In order to copy the image file, you need a disk imager tool. You can use Win32DiskImager to copy Armbian Image file to your micro-sd card.
If you are using the fresh Armbian Image, you need at least 2GB of micro-sd card. If it is more 2GB, when you insert micro-sd and power up OPZ, it will resize partition to fit to the size of your micro-sd card.
If you are using Vendiverse Armbian Image, you need at least 8GB of micro-sd card.
To start preparing your boot micro-sd card, please download Win32DiskImager using the link below:Win32DiskImager
Also, you may need to format your micro-sd card. You can use SDFormatter to properly format your micro-sd card. You can download it using the link below:[1]
After formatting micro-sd card, open up Win32DiskImager and select the image file you have downloaded and extracted, select the drive of inserted micro-sd card and click "Write".
Win32DiskImager Screenshot
Now you are ready to insert micro-sd card into OPZ and power it up.
Caution: Before you power up your OPZ, disconnect IDC Flat Cable that connects VMC Board and OPZ. For the first use and powering up for test purposes, always disconnect OPZ from VMC Board and power-up OPZ using a micro usb cable.
If you have completed the steps above and powered up your OPZ, small yellow led should be lit on OPZ. If you can not see yellow led lit even after two minutes of powering up, something might have gone wrong. Check or repeated the steps above and try again.
If you see yellow led lit on OPZ (close to micro-sd card slot facing top side), it means it has booted successfully and ready to be connected.
Although OPZ has a built-in wifi, it is not configured to connect to any access point in the beginning. Thus, you need to connect OPZ to a network switch or use the ethernet port on your modem/router and establish a wired network. OPZ is configured to obtain an IP address from the network. To access OPZ, you need the IP address of the OPZ that DHCP server on your router/modem has assigned. You can use management interface of your modem/router to see IP address of OPZ. Check for "orangepizero" as the host name on the list of ip addresses assigned.
Finding IP Address Assigned by Modem/Router DHCP
Once you have the IP address of OPZ, access to the terminal using a SSH client. (Putty SSH Client Download Page)
If you have downloaded Armbian Fresh Image,rootpassword is1234. After you login, it will ask some installation questions and require you to change the root password.
If you have downloaded Vendiverse Image,rootpassword isr1o2o3t4. Vendiverse application will be already started and running on the background when you power-up OPZ using Vendiverse Image.
SSH Terminal Access to OPZ Using Putty
Vendiverse Python application resides in the folder below:
/home/eliverse/bin
Important! If you have not programmend AVRs, it is not recommended running Vendiverse Python Application. Please proceed to Programming AVRs and complete the steps before you run the application.
If you want to run Vendiverse application, you need type command below:
cd /home/eliverse/bin
python vendiverse.py
If you have attached an Character LCD Screen to Vendiverse VMC Board and completed the steps above without any errors, you should be seeing IDLE screen of Vendiverse below:
Vendiverse Idle Screen
Vendiverse VMC Board uses Atmega AVRs for controlling peripherals connected to it. There are 3 AVRs and each is assigned a module on VMC Board. These modules are listed below. Every AVR carries out a different job and each has its own software. You can download compiled HEX files of software or you can download the source codes, compile and upload it to AVR. You will need an AVR programmer. You can use Arduino UNO with DIP packages to program AVRs. Also if you find it hard to program Atmega8 AVRs, you can use Atmega328 AVR instead and program it using Arduino Uno. Source codes are available as Arduino Sketches. (.ino files) During design, I have chosen the cheapest parts that can do the job and Atmega8 is used whenever possible to cut the production costs. If you don't have cost concerns, you can use Atmega328 instead of Atmega8 for your convenience.
Vendiverse AVR Modules
| Module | AVR | OPZ Interface | Address |
|---|---|---|---|
| Environment Module | Atmega8 | I2C, TWI-1 | 0x11 |
| IO Module | Atmega8 | I2C, TWI-1 | 0x10 |
| MDB Module | Atmega328 | UART-1 |
You can download compiled binaries using the links below. If your browser opens up text file when you click the links, try right clicking on links and selecting 'Save as' or 'Download'.
AVR Binaries
| Module | Dowload Link |
|---|---|
| Environment Module | ENV.hex |
| IO Module | IO.hex |
| MDB Module | MDB.hex |
Once you have downloaded pre-compiled binaries for AVRs, you can use AVRDude to program AVRs. You can use the most convenient way that you like for programming AVRs. Here, I will briefly describe using AVRDude and show basic commands to use it. If you haven't downloaded AVRDude yet, please download the latest version using the link below:
After you downlad AVRDude, open up the command prompt and go to the folder where avrdude.exe resides. Use the command below to program your AVR.
For Atmega8:
avrdude.exe -Cavrdude.conf -cstk500v1 -pm8 -PCOM5 -b19200 -B1 -U flash:w:ENV.hex
For Atmega328:
avrdude.exe -Cavrdude.conf -cstk500v1 -pm328 -PCOM5 -b19200 -B1 -U flash:w:MDB.hex
Replace COM5 with the com port your programmer is connected. Replace ENV.hex or MDB.hex with the file you want to program.
Once you have completed all the steps above, connect to OPZ as described in Connecting to OPZ above and check if all the modules are connected properly and running by issuing the command below in the terminal:
i2cdetect -y 0
This command will scan the I2C TWI-0 bus and shows the occupied addresses on the bus. You should see an address list that looks like below:
I2C TWI-0 Bus Addresses of Modules
Module addresses are listed below. Check if you can see associated addresses on the list. If not, there is a problem with that module and OPZ will not be able to connect and use that module.
I2C TWI-0 Modules and Addresses
| Module | Address |
|---|---|
| DS1307 Real Time Clock | 0x68 |
| Character LCD Display | 0x3F |
| IO & Keypad Module | 0x10 |
| Environment Module | 0x11 |
In order to use DS1307 Real Time Clock as linux hardware clock, we need to register the module as new hardware clock device. If are using Vendiverse Armbian Image, you don't need to register it as it is already registered.
To register DS1307 Real Time Clock as hardware clock, issue the command below:
echo ds1307 0x68 > /sys/class/i2c-adapter/i2c-0/new_device
Now, you should be able to see the module as a new device on /dev/rtc1 when you list devices like below:
Registering RTC Module as New Device
Now, you should be able to read and set date and time on RTC Module. When Vendiverse Board is powered-off, DS1307 RTC Module will still be ticking the time using the lithium cell battery on it. Battery will only power the RTC module since it is isolated from the board power source.
To set system date to the date on RTC Module, issue the command below:
hwclock -f /dev/rtc1 -s
To set RTC Module's date to system date , issue the command below:
hwclock -f /dev/rtc1 -w
To display date of RTC Module, issue the command below:
hwclock -f /dev/rtc1 -r
Below you can find a screenshot of changing the system date and then writing system date to RTC Module and reading the date from RTC Module to make sure it is set.
Changing System Date and Writing System Date to RTC Module
Keypad is controlled by IO Module (Atmega8 AVR located under OPZ). In order to access IO Module, you have to make sure that IO Module is programmed with IO.hex and correctly placed and running. IO Module is connected to I2C TWI-0 bus on address 0x10. IO Module uses one 74HC595 and one CD4091 to scan through rows and columns of a 4x4 Keypad and detects any keypad button press and sends it to OPZ. IO Module is a slave I2C device, meaning that it can not directly send input to OPZ. Rather, OPZ asks for any input and IO Module sends the response. This mechanism is similar to serial polling. Slave devices can not reply, unless they are asked.
In order check the attached keypad, you can use python library that resides in /home/eliverse/bin folder. Issue the command below once you are in the bin folder:
python keypad_mega8.py
If IO Module ise connected and running, you will see an output like the image below:
Vendiverse Keypad Library Test Output
If there is no keypress, module will answers with "-". Otherwise, it will output the corresponding key. If the output differs from the keypad button you press, try changing rows and columns on 8 PIN keypad connector. (J-KEYPAD) Some keypads have different pin output for rows and columns so you need to find the correct order of pins. J-KEYPAD pins will have a layout starting from left to right: R1-R2-R3-R4-C1-C2-C3-C4 (R for rows, C for columns)
Vendiverse Generic 4x4 Keypad In Action
Vendiverse VMC Board has an administrative access button. When you press this button on the board, you will switch to administrative menu. Using administrative menu, you can carry out all administrative functionalities such as changing prices, setting minimum and maximum prices, change date and time and access sales reports. This button is placed on VMC Board because it should not be placed anywhere where customer can access. Operator of vending machine will unlock the door and only an operator should be accessing this button.
To test button, you can issue command from the terminal just like testing the keypad explained above.
python keypad_mega8.py
After issuing command, press the administrative menu button and you should be seeing 'Z' as input on the screen.
Vendiverse VMC Administrative Menu Button
Vendiverse VMC Board has 4 status LEDs available for general purpose use. You can assign error or status codes to these LEDs for debugging purposes. For example, if there is a problem with payment devices, you can blink error led (red) two times. If IO module is running, you can blink green or blue led as a heart beat of the system. It is all up to you on how to use these LEDs. There is no default action defined for these leds in Vendiverse application.
Vendiverse VMC Board Status LEDs
LEDs are controlled by IO Module which is located on I2C TWI-0 Bus on address 0x10. To test led functionality, you can issue commands manually on the terminal:
i2cset -y 0 0x10**0x0F**
0x0F is the hex representation of bits to light up leds. If you want to light up LED1, byte you need send is 0b00000001 (0x01). Similarly, for LED2 the byte is 0b00000010 (0x02). If you want to light up multiple LEDs, you need toORcorresponding bits. For all leds, it is 0b00001111 (0x0F)
Vendiverse VMC Board has 4 general purpose relays. Relays can switch 220V AC or other DC sources. If you have ordered an Vendiverse VMC Board rather than building your own, you will have 4 relays with 5V Coils and 250V 10A AC output. These relays are controlled by Environment module. You can use these relays to switch cooler fan or compressors, interior lights. Vendiverse Application currently uses 2 relays for controlling cooler compressor and cooler fan. One relay is used to control 24V power source (MDB Payment devices uses 24-35V VDC power source and they are powered up after OPZ successfully boots.) There is one auxillary relay that you can use to switch anything according to your needs.
Vendiverse VMC Board General Purpose Relays
As mentioned above, relays are controlled by Environment module. Environment module is connected to OPZ on I2C TWI-0 bus with address 0x11. In order to test relays, you can issue the command on terminal below:
i2cset -y 0 0x11**0x83**
Vendiverse Controlling Relays
Note that, first relay starts with 0x83 and increments by one. In order to switch on fourth relay, you should send 0x86 byte as command. Also, note that to switch on, you need to set most significant bit to 1 and to switch off, you should set it to 0. To switch on first relay, send 0x83 or to switch off, send 0x03.
First three numbers are assigned for controlling LED stripes for interior lighting. If you are using Vendiverse 0.1 board, you can only use 12V LED stripes. In later boards, you can select the power source between 12V and 24V with a jumper. You can switch LED stripe power using lower 3 numbers.
Vendiverse VMC Board has two temperature sensor ports. These ports are configured to work with digital temperature sensorDHT-11. DHT-11 sensor not only measures temperature, it also measures humidity. Also, it has a long life and good accuracy that do not need calibration. You can place two sensors wherever you want inside the vending cabin and measure the temperature of two different points. Vendiverse Application supports setting maximum and minimum temperature levels of different spots and if configured, it can calculate the mean temperature of two sensors and start or stop the cooler or fans based on these minimum and maximum values. Below, you can find the ports for two temperature sensors on Vendiverse VMC Board.
Vendiverse VMC Board Temperature (DHT-11) Ports
Below you can find correct pin-out of DHT-11 sensors. If you want to place sensors in a distant place, you can use CAT-5 or CAT-6 twisted network cables for extension. Over CAT-5 and CAT-6 cables, VMC Board and DHT-11 sensors can reliably communicate up to 3 meters.
VMC Board DHT-11 Pin-out
Once you have connected DHT-11 sensors to VMC Board, you can read the values by issuing the command in the terminal below:
i2cget -y 0 0x11
Reading Temperature Using Command Line
This command will read the first temperature sensor and print the value in Celcius degrees.0x19is the hex representation of 25 degrees Celcius. If you read 99 degrees celcius, it means that read attempt failed because of a check-sum error. If there is a check-sum error, it means that cables are either too long or there is a lot of electromagnetic noise in the environment or the sensor is damaged. If you read 100 degrees celcius, it means that VMC can not communicate with sensor or there is no sensor connected or sensor is permanently damaged.
Vendiverse uses an Atmega328 AVR to communicate with MDB payment devices. MDB uses 9 Bit 9600 baud UART communication between the master and the devices. Since OPZ does not have an hardware support for 9 Bit Serial Communication, an Atmega328 AVR is used to handle the low level MDB communication. Atmega328 AVR is connected to OPZ's UART-1 port and communicates over MDB and sends it to OPZ as more human readable data.
To check if MDB Module is working correctly, issue the command below to communicate with Atmega328 AVR.
screen /dev/ttyS1
Using Screen Command to Access MDB Module
This will open up a screen session (for more info aboutscreencommand, check linux manuals) that connects to /dev/ttyS1 serial communication device. MDB AVR will echo what you type. In order to start MDB protocol, you need to enter '-'. Once MDB AVR receives this command, it will start identifying and configuring connected MDB Payment Devices. During initialization of MDB Devices, it will print human readable information about found payment devices. You can checkVendiverse MDB Module for more on these responses and what they mean. For a quick overview, here are the responses that you will get when no MDB payment device is connected.
MDB Module Serial Response
Response from MDB Module
| Response | Remarks |
|---|---|
| C.INIT | Initializing coin acceptor |
| C.ERROR.NC | Coin acceptor not connected. Skipping initialization. |
| B.INIT | Initializing bill acceptor |
| B.ERROR.NC | Bill validator not connected. Skipping Initialization. |
When you are finished with checking MDB module, you canexit screen sessionby pressing CTRL+a and then k and answering 'yes' to exit prompt.
Product sensor senses product drop and makes sure the selected item/product is delivered to customer. If not, it will try to power vending motors in little increments to check if the item is stuck at sprials. After a small increment, if the product is still not delivered, VMC will refund the customer and mark the shelf as out-of-stock or out-of-service and disable the shelf so that other customers can not select it again.
Product sensor port is connected to IO module and you can find description of pins below. Product sensor is active-high, meaning that if a product drop is sensed, it should pull the signal pin high (5V), otherwise, it should stay low (grounded).
Vendiverse VMC Board Product Sensor Port
If you are not using product sensor, you should connect ground and signal pin with a jumper so that IO Module will not trigger a product drop. If you leave it open, IO Module will be interrupted by lingering state of signal pin and each interrupt or electromagnetic noise in the environment will block the keypad operation. So it is strictly advised that you connect it to ground with a jumper if you are not planning using a product drop sensor. (GND-SIGNAL-5V starting from left)
If you are not sure on where to obtain a product drop sensor, you can build your own Making a Vendiverse Product Drop Sensor
To test product sensor port of Vendiverse VMC Board, you can continue same steps as described in Checking Keypad. The only difference is that when pulled high (you can place a jumper cable between signal and 5V pin), you should see a 'P' character as the output.