¶ Overview
HuskyLens is an easy-to-use AI machine vision sensor. It can learn to detect objects, faces, lines, colors and tags. Everyone can easily program the HuskyLens through the MicroBlocks HuskyLens Library.
HuskyLens library is 100% written in MicroBlocks and all the code of the library blocks can be examined by right clicking the blocks and selecting show block definition.
The picture below shows all the components and functionality provided by the HuskyLens.
For a detailed description of the HuskyLens features, please refer to the product WIKI
The HuskyLens library provides support for:
- I2C connectivity
- Request recognized objects from HuskyLens
- Request only one object by id
- Learn the current recognized object with any id
- Write text input on HuskyLens screen
- Save and Load files to SDcard
- Save a screenshot or picture to SDcard
- Set a custom name for any learned object
¶ User Guide
HuskyLens has two object types: Blocks and Arrows.
Faces, colors, objects, and tags are Block type.
Lines are Arrow type.
HuskyLens can learn to recognize Objects and assigns an ID number to each learned Object. The ID numbers are consecutive.
Here is a sequence that needs to be followed in order to obtain any detected object information from the HuskyLens:
| 1. Train HL with any data type for the operation desired using the learn button. 2. Initialize HL and set i2c address 3. Select Algorithm desired 4. Make a request for Blocks or Arrows 5. Analyze returned data and take action |
 |
|---|
This example makes use of the Blocks request and Face Recog algorithm.
HuskyLens, assigns 0 to ID number for unlearned objects.
¶ Summary of Blocks
For each block, there is a short description entry and a detailed block description. You can click on block pictures in the short description table to access the details.
| Short Description | |
|---|---|
 |
Initializes HuskyLens Library & Sets I2C address |
 |
Changes recognition algorithm |
 |
Requests recognized objects from HuskyLens |
 |
Requests only one object by id from HuskyLens |
 |
Gets Block details from HuskyData |
 |
Gets Arrow details from HuskyData |
 |
Gets Info details from HuskyData |
 |
Used for maintenance operations |
 |
Writes text to HuskyLens screen |
 |
Saves and Loads file to SDcard |
 |
Learns recognized object by id |
 |
Sets custom name for a learned object |
 |
Learns recognized object with id and name |
¶ Working with Library Blocks
HuskyLens Library has two distinct types of block shapes:
-
oval: these are reporter blocks that return some kind of information back. The user would normally either assign these to a project variable or use it in a suitable input slot of other blocks.
-
rectangular: these are command blocks that perform a programmed function and do not return any information.
REMEMBER:
From time to time the camera hardware might get into a state of unreliable operation. If all attempts to normally restore the operation is not successful, a factory reset of the camera will revert all settings and data acquired up to the reset point to the original startup condition.
Data on the SDcard is NOT affected by this action.
¶ Block Descriptions
#hl-init-&-set-i2caddr
¶ HL init set I2Caddr
Used to initialize the library and set the i2c address of the camera. Default address is 32.
This block needs to be used before any of the other blocks are used in a program.
If i2c address not set , MicroBlocks will give i2c error.
¶ Sample Code
¶ HL change algorithm
This block is used to select one of the many algorithms supported.
Algorithms: Face Recognition, Object Tracking, Object Recognition, Line Tracking, Color Recognition, Tag Recognition, Object Classification.
¶ Sample Code
¶ HL request
Used to request objects from HuskyLens.
Object types: Blocks, Arrows, Learned Blocks, Learned Arrows
After the request, data details are saved in HuskyData.
¶ Sample Code
In the example above, when button-A is pressed, MicroBlocks makes a request for Blocks from HuskyLens.
HuskyLens detects 2 different faces and sends back the response, which is stored in HuskyData.
HusyData contains a summary info block (I) and two detected face blocks (B).
For details of HuskyData content refer to the What is the HuskyData? section below.
¶ HL request by id
Used to request learned objects from HuskyLens that match an ID number. Whenever an object is learned by HuskyLens, it is assigned an ID number.
¶ Sample Code
In the above example, when button-A is pressed, MicroBlocks makes a request for learned Blocks with ID# 1 from Huskylens.
HuskyLens has recognized 2 different faces and sends back the response for the one with ID# 1, which is stored in HuskyData.
HusyData contains a summary info block (I) and one detected face block (B).
¶ HL get block
Used to get data details of detected block objects. In case of multiple object detection, index number can be used to extract information of the (index)th object.
- X Center of Block
- Y Center of Block
- Width of Block
- Height of Block
- ID of Block
¶ Sample Code
In the above example, when button-A is pressed, MicroBlocks makes a request for Blocks from HuskyLens.
HuskyLens has recognized 1 face and sends back the response, which is stored in HuskyData.
HusyData contains a summary info block (I) and one detected face block (B).
Then we use the say block to display the detected object's data.
¶ HL get arrow
Used to get data details for detected arrow objects. In case of multiple object detection, index number can be used to extract information of the (index)th object.
- X Origin of Arrow
- Y Origin of Arrow
- X Target of Arrow
- Y Target of Arrow
- ID of Arrow
¶ Sample Code
In the above example, when button-A is pressed, MicroBlocks makes a request for Arrows from HuskyLens.
HuskyLens has detected 1 arrow and sends back the response, which is stored in HuskyData.
HusyData contains a summary info block (I) and one detected arrow block (A).
Then we use the say block to display the detected object's data.
¶ HL get info
This block used to get summary information for the detected objects:
- Object Count : numbers of blocks and arrows
- Learned Count : number of learned IDs for the algorithm selected
- Frame Number : Current Frame Number
¶ Sample Code
In the above example, when button-A is pressed, MicroBlocks makes a request for Blocks from HuskyLens.
HuskyLens has recognized 2 faces and sends back the response, which is stored in HuskyData.
HusyData contains a summary info block (I) and two detected face blocks (B). Below result display shows the data breakdown for the summary info data (I).
¶ HL do
The block is used for many operations:
- Knock: Used for test connection with HuskyLens.
- Save screenshot to HuskyLens sdcard.
- Save picture to HuskyLens sdcard.
- Clean the screen: Clears the texts on the screen.
- Forget learned objects: Forgets learned blocks and arrows.
- is pro: ask HuskyLens for the model. Returns HuskyLens is pro or not.
- firmware version: Check if the onboard firmware is out of date.
¶ Knock
Used for testing the connection with HuskyLens. If the connection is operational, OK is returned.
¶ Save Picture and Save Screenshot
This command saves what is on the screen to the SDcard.
If save picture is used, then only the camera image is saved.
If save screenshot is used, then the camera image and any other generated overlaying GUI information is saved (object boundaries, ID numbers, assigned names, text info displayed).
Files are saved to the SDcard in the BMP format and named in ascending numerical filename order. eg: 1.bmp, 2.bmp, etc.
¶ Sample Code
Picture:
Screenshot:
¶ Clear the screen
Clears any text displayed on the screen.
Text may have been written to screen using the HL Write command.
¶ Sample Code
¶ Forget Learned Objects
Forgets learned objects for the current running algorithm.
¶ Sample Code
¶ is pro
Checks what model your HuskyLens is.
Returns HuskyLens is pro or not.
¶ Sample Code
¶ Firmware Version
Checks if the onboard firmware is out of date. If it is an old firmware, there will be a UI message that pops up on the screen. If the firmware is current, OK is returned.
¶ Sample Code
¶ HL write
This block displays the text input at the given display coordinates.
Top left corner is x=0, y=0.
Text length must be less than 20.
X must be 0-319
Y must be 0 -239.
¶ Sample Code
In the above example, when button-A is pressed, MicroBlocks makes a request for Blocks from HuskyLens.
HuskyLens has recognized 2 faces and sends back the response, which is stored in HuskyData.
HuskyData contains a summary info block (I) and two detected face blocks (B). We access the "object count" property of the Info block and use it to iterate over the detected images and write their names under each image.
¶ HL file
This command handles the Saving and Loading of the current learned object data to/from the SDcard.
It is used to save the learned objects' information after lengthy training sessions. Once saved, these files can later be loaded under program control and used by the recognition process.
The file name on the SDcard will be the in the format:
"AlgorithmName_Backup_FileNum.conf".
File number range is 0-65535.
Firmware limitations for SDcard FILE Information:
Currently, the firmware saves all files to the SDcard with the exact same timestamp information. Therefore, it is impossible to identify files by modification dates. Since the only portion of the file info under user control is the filenumber, it is suggested that the filenumber be used in a coded manner to distinguish the various saved versions of the same algorithm's training data.
Also, there is no checking or warning for saves that result in filenames that match an existing name on the SDcard. If not careful, a lot of data can be lost with a simple click of the mouse.
Finally, there is no way to edit / modify existing training data files.
¶ Sample Code
The filename saved to the SDcard will be named FaceRecognition_Backup_1.conf.
¶ HL learn by id
The block is used to learn the current recognized object with an ID.
ID number must be 0 - 255 and consecutive among the learned objects for the algorithm.
Also, the object to be learned must not be already in the "learned" category; meaning that it must be surrounded by a "white" box and not any other color.
There is a notation in the manufacturer's firmware, that this feature is only to be used with the Object Classification algorithm. However, all testing indicates that names can be assigned to any detected object.
Nevertheless, user beware and verify for your own purposes.
¶ Sample Code
Before we execute the above example, we have selected the "Face Recog" algorithm and deleted all learned objects to start with.
As such, when the camera is pointed at pictures, it recognizes the two faces and it surrounds them by two white boxes marked "Face", meaning recognized but not learned (no ID numbers means not learned).
Then we focus the camera onto the right face and wait for it to dispay the white box surrounding it. This means the image is recognized but not learned yet.
At this point, for us to assign the correct ID number in the HL learn by id block in the sample program, we need to know how many "learned objects" there are in the Face Recog algorithm. To find this out, we can execute a HL request command with "Blocks" option. Clicking on this block with the camera pointed at the right face, will capture the image summary info and the block information.
HL request command will set the HuskyData with the information we need.
Now we can use the HL get info block with the "Learned Count" option.
As can be seen in the Learned Count display, there are 0 learned blocks in the algorithm. Thus, we can start our ID number with 1. And that is the number we code into our sample program block.
Finaly, we are ready to execute our sample program, as we point the camera to the right face. When the "Learn status: OK" is displayed, we will notice that the white box around the right face on the camera screen is replaced by a BLUE box with the notation Face:ID1.
ASSIGNING ID Numbers:
As mentioned above, all ID numbers have to be sequential, starting at the last learned ID number for the algorithm plus 1 or 1 if none is learned yet. Skipping numbers or trying to learn an already learned ID number will result in no Learning even though the block will return an OK for the execution status.
Remember that the last learned ID number can be obtained using the HL get info block with the Learned Count option.
¶ HL set custom name
This Block is used to set a custom name for an already learned object; one with an ID number assigned. It provides a quick way to assign names to learned objects programmatically.
An assigned name can be erased by execuing the command with a blank name. When an assigned name for an object is erased, its display notation changes to the default object notation for the algorithm selected.
Name length must be less than 20.
ID number used must be 0 - 255.
While the name assigned is programmatically not of any use, the assigned name is displayed on the screen and makes object identification by the user easier.
¶ Sample Code
In the above example, we start out with two learned faces in the Face Recognition algorithm, with ID numbers 1 and 2.
Upon execution of the sample program, the left face with ID number 1 is assigned the name "Turgut" and the right face with ID number 2 is assigned the name "Murat". Camera display shows the new designations for the two faces.
¶ HL learn id and name
This block is a shortcut block that does two things at once:
- it learns the currently recognized object with an assigned ID number
- and it assigns it a name at the same time
Name length must be less than 20.
ID number used must be 0 - 255.
Using this block is the equivalent of using the blocks:
It is a quick way to learn and name many objects back to back programmatically.
¶ Sample Code
¶ What is the HuskyData?
HuskyData is a list that contains data details of requested objects from the camera. One can think of it as the packet of response that is sent back from the camera for each request it processes.
¶ An example of HuskyData, after a Blocks request
¶ An example of HuskyData, after an Arrows request
For each request made, HuskyLens sends back a packet of response that includes the following information:
- First group of information sent is called Info Data.
- This is followed by either a set of Block Data, if a Blocks request was made;
or a set of Arrow Data, if an arrow request was made.
In a MicroBlocks program, this information is stored in the HuskyData variable.
Let's break down the HuskyData information blocks:
¶ Info Data
Info Data contains 3 pieces of information:
- Object Count : Numbers of blocks or arrows
- Learned Count : Numbers of learned blocks or arrows
- Frame Number : Current Frame Number
¶ An example of Info Data:
| Data | Description |
|---|---|
| I 2 8391 |
indicates that this is Info Data. means numbers of blocks or arrows learned is 2 is the frame number |
¶ Block Data
Block Data contains 5 pieces of information for each block:
- X center of block.
- Y center of block.
- Width of block.
- Height of block.
- ID number of block.
¶ An example of Block Data:
| Data | Description |
|---|---|
| B 84 132 65 112 2 |
indicates that this is Block Data X center of this block Y center of this block Width of this block Height of this block is ID number of this block |
¶ Arrow Data
Arrow Data contains 5 pieces of information for each Arrow:
- X Origin of arrow.
- Y Origin of arrow.
- X Target of arrow.
- Y Target of arrow.
- ID number of arrow.
¶ An example of Arrow Data:
| Data | Description |
|---|---|
| A 192 132 88 14 1 |
indicates that this is Arrow Data X origin of this arrow Y origin of this arrow X target of this arrow Y target of this arrow equal is ID number of this block |