Month: November 2017

hiku, receiving events

hiku, receiving events

In this article on my hiku series I will focus on receiving events. In my article hiku, getting started I already showed some sample code to receive events. In this article, I will dig a little deeper and explain when each event is triggered.

The hiku comes with an accompanying app. The app contains the shopping list which gets filled by scanning items with your hiku (provided the hiku recognizes the barcode). You can also add items to your shopping list in the app, by scanning or typing. All of these methods trigger an event for your webhook.

Apart from the two event types that are triggered to add something, there are also two other types of events, a battery level event and a device registered event.

Event types

Let’s look a little more in depth at the four event types, what they mean and what data you can expect in them. In the hiku, getting started article I already showed how to receive the post data (through php://input). The data you receive is json formatted. I won’t go into detail what json is, others have already done that. In PHP there is an easy function called json_decode which converts the json to an object or an associative array. What you need to know about the json you receive from hiku is that it will have a data section which contains the information you need for the four event types.

The data for each event is different. Some fields are optional while others are required. Let’s look at the data in these event types, starting with the two simple events, device registered and battery level.

DEVICE_REGISTERED

A device registered event is trigger by a new user registering their hiku to your app. When you receive such an event you will get the following information:

                  Required/
Parameter         Optional       Type     Description/value
eventId           Required       Int      4
eventDesc         Required       String   DEVICE_REGISTERED
token             Required       HString  Unique token identifying the user
serialNumber      Required       HString  hiku serial number

After this event you know you can receive more events from this user, so it makes sense to store at least the token in a database. The token will be used in other events to identify the user.

DEVICE_BATTERY_LEVEL

When a hiku is registered to your app using the DEVICE_REGISTERED event you will periodically get a DEVICE_BATTERY_LEVEL event. You can use this show the hiku battery level in your app. You will get the following information:

                 Required/
Parameter        Optional     Type       Description/value
eventId          Required     Int        3
eventDesc        Required     String     DEVICE_BATTERY_LEVEL
token            Required     HString    Unique token identifying the user
batteryLevel     Required     String     Battery level, percentage from
                                         0-100
serialNumber     Required     HString    hiku serial number

Receiving scans from your hiku

Before I go into the two event types that are triggered by the hiku to signal a new product needs to be added to some list, let’s first look at how these events are triggered. There are basically two sources for these triggers, the hiku device and the hiku app.

With the hiku device you can either scan a code or talk to it If you scan a barcode with the hiku there are two possibilities; the barcode is recognized in the hiku database or it is not. If the hiku recognizes the barcode, it will beep to let the user know it recognized the barcode and than two things will happen. It will add the product to the shopping list in the hiku app (if the user has not changed the checkbox in the app) and it will send a PRODUCT_ENTRY event to your webhook. If the hiku does not recognize the barcode, it will send an EAN_NOT_FOUND containing the EAN it did not recognize. Besides scanning a barcode, you can also talk to the hiku to add items on the shopping list. In this case you will also get a PRODUCT_ENTRY event but instead of containing an EAN to identify the product you will get a string with the name of the product and access to the WAV file with the audio.

In the hiku app you can also add products. You can do this by selecting your favorites, which could include an EAN, or by adding items by name. In both cases you will get a PRODUCT_ENTRY event. You can also add products to the shopping list using the provided API, which will be discussed in a later article. When the API is used, a PRODUCT_ENTRY event is also generated. We will get into more detail why that is important when we cover the hiku app API.

Ok, so now let’s take a look at the two remaining events:

PRODUCT_ENTRY

The PRODUCT_ENTRY event will contain the following information:

                Required/
Parameter       Optional     Type       Description/value
eventId         Required     Int        1
eventDesc       Required     String     PRODUCT_ENTRY
token           Required     HString    Unique token identifying the user
id              Required     Int        Shoplist entry id of the product
aisle_id        Required     Int        Aisle id for the product
name            Required     UString    Product name/description
ean             Required     String     Barcode/EAN can be NULL
audioPath       Required     String     URL to WAV file containing voice
                                        Can be empty
serialNumber    Optional     HString    hiku serial number if hiku was used

As described above, there are different scenarios which can give a PRODUCT_ENTRY event. In all cases the first 5 parameters, eventId, eventDesc, token, id and aisle_id will be filled. Even though the aisle_id is not in the documentation, so far I have always seen it.

This leaves the last 4 parameters. So far, I have seen the name always filled in with something, which is also what the documentation suggest, even for spoken products. The voice to string function they use is remarkably good. The ean parameter will be null if you speak a product to the hiku or if you type a product in the app. If you pick a product from your regulars list and that item contains the ean code, than it will show up in your PRODUCT_ENTRY event. The audioPath will be empty unless you spoke to your hiku. This leaves the parameter serialNumber which you will only get if a hiku was used. If you use the app or the API, this parameter will not be in the PRODUCT_ENTRY event.

EAN_NOT_FOUND

The EAN_NOT_FOUND event is a lot simpler than the PRODUCT_ENTRY event. Let’s look at the information:

                Required/
Parameter       Optional     Type       Description/value
eventId         Required     Int        2
eventDesc       Required     String     EAN_NOT_FOUND
token           Required     HString    Unique token identifying the user
eanNotFound     Required     String     Unrecognized barcode

As you can see, it is rather straight forward. The user identified by token scanned a barcode with either the hiku or with the app. In the current implementation of the event you cannot tell the difference.

Putting it all together

The next step in development of your webhook is decoding the received JSON, determine what to do and after process send a response. Instead of listing it here, it makes more sense to get it from GitHub, in the directory 03 – Receiving events.

github-mark-32px Available on GitHub

Continue reading

The next articles in the hiku serie:

  • hiku, understanding the shopping cart
  • hiku, updating the shopping cart

or read some of the previous articles in the hiku serie:

hiku, getting started

hiku, getting started

Developing an application for the hiku is not too difficult. What you need is the following:

  • a hiku
  • a publicly accessible server that runs an https server and your flavor of programming language (I am using php)
  • a phone or tablet
  • an app id with matching secret

You can buy a hiku online, either with hiku directly or through Amazon. Having access to a webserver that runs https (secure http) is not hard to come by. If you do not have this yet, I am sure you can google this. You need a phone or tablet with you can use to run the hiku app. You need the app to program the wifi credentials into the hiku. Finally you need to get an app id and matching secret from hiku. I will get to that later.

I am going to assume you have your hiku now, you have access to an http server where you can put your code and a phone or tablet with the hiku app. For iOS this is the link. So far the iOS app is only available in the US store. The documentation for setting up your hiku can be found on the hiku website along with some other support articles.

Once you are set up, try scanning some products. The hiku database should recognize a lot of US products but if you are not in the US, it might not recognize your local products. When you scan an unknown product you can add it yourself. You should be able to scan US products like the jar of Nutella:

http://hier.familiebenda.nl/global.j-tools.net/Includes/Barcode/barcode.php?code=80050865&scale=1.6

Scanning from my laptop screen did not work but you should be able to scan from your phone or tablet.

Once you are famliar with scanning, it is time to start your own app and get credentials. The next article will cover receiving events in detail but I would suggest creating a simple program to receive the webhooks and save the output. That way you can read back events and familiarize yourself with the contents. Also the DEVICE_REGISTERED event is only fired once for your hiku so if you save it, you can at least replay it. For now, you can use the following file and the details will be explained in the next article.

github-mark-32px Available on GitHub

<?php
//
// Set the location of your data directory
//
$dirData = "./";

//
// Retrieve the body part of the POST to our webhook
//
$postBody = file_get_contents('php://input');

//
// String with date/time for use in the filename
//
$time = strftime("%Y%m%d-%H.%M.%S");

//
// Save the body of the POST to a file
//
file_put_contents($dirData.$time.".body.txt",$postBody);

//
// Prepare a json string in the hiku format for ok
//
$json = array("response"=>array("status"=>"ok"));
$jsonstring = json_encode($json);

//
// Send the json file as response
//
header('Content-type: application/json');
print $jsonstring;
?>

Once you have uploaded this to your https server, test it to make sure it works and write down the complete url. Remember, it does not need to be index.php. In my case I use beep.php because hiku calls a scan a beep.

You are now set to ask for an app id and accompanying secret which you will need to update the shopping cart.

Send an email to devrel@hiku.us, tell them that you are developing an app, tell them what the app is supposed to do, give them the link to your webhook and the serial of the hiku that you plan to use for testing. You can find the serial in the hiku app by selecting menu, hiku (bottom left) and than clicking on your hiku’s name. Also tell them that you are ready to receive all event types (described in the next article).

When you receive an email from them with an app_id and secret, you are ready for one of the next articles in the hiku serie:

or read some of the previous articles in the hiku serie:

 

Barcodes, EAN-8/13, create your own

Barcodes, EAN-8/13, create your own

Barcodes have been around for quite some time and you can see them everyone, on books and for example on your groceries. A barcode, by the definition of Wikipedia:

A barcode is an optical, machine-readable, representation of data

Basically a set of thick and thin black lines seperated by white lines which represent a code. I do not plan to go on and on about barcodes; I plan to focus on two codes used for marking products in your grocery store, EAN-13 and the smaller version EAN-8. The EAN-13, European Article Number or International Article Number is a set of 13 digits which together describe a unique product in the world.

So why this interest in barcodes? Well because I have been coding for the hiku, a small refrigerator magnet scanner which can read barcodes and send them to their shopping cart app or perhaps to your application.

Let’s look deeper into the EAN-13 code. It’s actually 12 digits and the last position is a checksum digit. If you are using a barcode generator of some sort, most likely it will be able to calculate the last digit for you. If you want to be able to do this, this is how:

Sum all of the digits in an even position (so the second, fourth, sixth etc digit) and multiply the sum by three. Next add the digits in the odd positions (so first, third etc). Your 13th digit will be the amount needed to make it even divisible by ten. An example:

http://hier.familiebenda.nl/global.j-tools.net/Includes/Barcode/barcode.php?code=294200001200&scale=1.6

In an even position (from left to right) 9,2,0,0,2 and 0, sum of which is 13 times 3 is 39
In an odd position (from left to right) 2,4,0,0,1 and 0. Sum of these is 7 plus 39 is 46. To make it evenly divisible by 10 you need 10-6=4 which makes the 13th digit a 4.

So how do companies know what to codes to use? Simple, they buy a range. The EAN-13 range is split up by country and within that country is sold to companies. The first two or three digits determine the country which you can look up in this list. As you can see, the range for books, ISBN, is also on that list. The range I was particularly interested in was the 20-29 range, in-store numbers. These numbers aren’t registered in some database but they are store specific. In my grocery store they are used for example to code fruits and vegetables that you weigh yourself, so for example:

http://hier.familiebenda.nl/global.j-tools.net/Includes/Barcode/barcode.php?code=217215700123&scale=1.6

This is the barcode for Jonagold apples (21721570) that will cost EUR 1.23 (0123) and the 5 is of course the checksum.

Well if they can do it, why shouldn’t I be able to create codes myself, not for use within a store but rather for quick and easy shopping. What I build with my hiku code is the ability to scan a recipe after which it adds all necessary ingredients to your shopping cart. An example is the first one listed in this article, 2942000012004. I decided to use the 29 range (hopefully not used at my grocery store), followed by 42 and than followed by 2 digits for the category (00 in this case) and than four digits for a sequential number (0012) and finally followed by the number of people you create the recipe for. That part I have not implemented yet but the barcode is ready for it.

Before I finish off, let’s quickly look at EAN-8. EAN-8 is the smaller brother of EAN-13 and was created for small packages where a long barcode would not fit. It is for the rest similar to EAN-13. In this case the first 7 digits are for encoding products and the last is again the checksum.

http://hier.familiebenda.nl/global.j-tools.net/Includes/Barcode/barcode.php?code=80050865&scale=1.6

The above code is for a jar of Nutella. The code is 8005086 and the checksum is 5. Similarly, calculating the checksum is done by adding the numbers in the ODD position from left to right, 8,0,0,6 and multiply by 3, so 8+0+0+6=14*3=42. Add the numbers in the even positions, 0,5,8 which brings 42+5+8=55 and than find what you need to get it divisible by 10, 60-55=5 which is the checksum.

The next articles in the hiku serie:

The previous articles in the hiku serie:

 

 

hiku, sample code, API

hiku, sample code, API

If you’ve haven’t, you can read my first article in the series on the hiku, online groceries, barcodes and hiku.

The hiku, a small wifi enabled barcode reader or as they call it themselves, the shopping button. From a materials perspective, it’s beautiful. The hard plastic outside is smooth and shiny and the aluminum button is beautiful but good design does not end there. The hiku can be put on your fridge with it’s magnetic back (assuming that magnets stick to your fridge of course) but they made sure that there is a rubber back so the hiku does not scratch your fridge. The bottom, depending on how you look at it, contains the scan window. The interior is protected by a glas window which itself is protected by a rubber edge so you can put the hiku on the table without scratching it or the table. All in all a beautiful design.

So what will it do for you? Well, if you live in the US you can use it to shop at Wallmart or Peabod. I know there are other companies also in other countries testing this device but even if your grocery store of choice is not among them, it is a great device for barcode reading and it’s API is open so you can integrate with them. I have been working on getting a demo ready for my grocery store of choice and will document what I have done in the next articles. In this article, let me share what they have online.

They have an API description and some sample code online on github:

https://github.com/hikuinc/hiku_shared

which amongst others contains their documentation of their API (version 1.5.6 at the time of writing) in the API directory.

They have also shared a sample app on github:

https://github.com/hikuinc/hiku_sample_app/

which also contains Getting started with hiku document. Even though I do have quite some programming experience, it does not include python and I was a bit lost when I read all this. After lots of reading and trying to understand what the Python code did, I managed to get the hiku working using php and in the next articles I will discuss in detail how to do it and include the code I have created.

High level the hiku solution contains two things, an API which you have to implement through a webhook which will send you the different events and an API which you can use to update the shopping cart in the app. Events, which you need to receive and process, are generated by the hiku (obviously) but also by the shopping cart app. Items in the shopping cart can be created within the app or by using their API.

Ready and exited to get your hiku going? Read on! You may skip the article on barcodes but it does give you a little background on barcodes in general and more specifically what you can do to create new ones. It’s not a long read 🙂

The previous article in the hiku serie:

Online groceries, barcodes and hiku

Online groceries, barcodes and hiku

I have been doing my groceries online for about 2 months now. The grocery store I go to tends to be very busy at the times that I can go which does not make it one of my favorite tasks. Luckily my grocery store also offers the option to prepare your shopping so you can pick it up at a counter or even bring it to your house within a 2 hour slot.

To order you can use a browser or an app and they even sync shopping cart with the same account. There are advantages to both but I like the app because it allows you to scan barcodes of the products you want. Aha!

So I started collecting barcodes of the products I buy frequently, put them in a database and using a php barcode generator I have a list of products that I can just quickly scan to put them on my shoppinglist instead of typing and clicking on the one I want.

The php barcode generator I use is PHP-Barcode 0.4. The newest version of this tool can be found on http://www.ashberg.de/php-barcode. It’s basic usage is simple, something like: barcode.php?code=294200001200&scale=1.6 would give you the EAN-13 barcode listed in the call.

After a few weeks of working this way, I found that using the app took to much time. It was fine for preparing the weeks grocery list but if you just wanted to add something quickly which I found I needed during the week, I noticed myself still writing it down.

Determined to make my grocery shopping life easier, I started looking online for a barcode reader. I thought I would hook one up to an ESP8266 through bluetooth and send the codes to a server. Than I found this nifty device called hiku.

hikuL

This could be what I was looking for, it scans barcodes and is connected to wifi. I bought one through Amazon and hoped I could get it to work to do what I want.

So how does it work? Well, it’s a small scan barcode reader that connects to your own wifi. It does that by using the app (iTunes link) which uses flashing to send the SSID and password to the device. Once it is connected you scan a barcode which it than sends to it’s own server to see if it recognizes it. If it does, it’s added to the shopping list in the same app.

There is an however though. The hiku is aimed at the US market, Walmart and Peapod have integrated with it, and it turns out that it doesn’t recognize most of my products. Reading online I figured it should be possible to integrate with them and fill the shopping cart of my local grocery store. So I emailed them to ask about API and integration and I emailed my grocery store (it’s a large store with locaties all around the country) asking them about the API for the shopping basket. The response for hiku was very fast and very supportive. I turns out they had some sample code and API documentation online. Unfortunately the reply from my grocery store was short and not sweet; we won’t help you. Not really what I was expecting but I can always reverse engineer their website. So I started with my successful hiku adventure which I will document in a few blogs:

I will put all of my code, which is written in PHP, online through github. The code is done and I am now using it to iron out some exception cases and of course some cleanup.