Kolban's Book on C.H.I.P.

Page 1

Table of Contents Introduction – The CHIP Book..................................................................................................................9 The CHIP story.........................................................................................................................................10 Introducing the CHIP...............................................................................................................................10 Physical architecture............................................................................................................................10 CPU.....................................................................................................................................................12 The storage subsyste.........................................................................................................................12 The !o"er syste................................................................................................................................12 #ideo out!ut........................................................................................................................................1$ %udio out!ut........................................................................................................................................1$ &eyboard in!ut....................................................................................................................................1$ Co!arison against 'as!berry Pi (ero...............................................................................................1) *etting +tarted.........................................................................................................................................1, -lashing ne" sot"are.........................................................................................................................1, Installing !ackages...................................................................................................................................2/ Installation tools..................................................................................................................................2/ a!tcache.........................................................................................................................................2 a!tile.............................................................................................................................................2$ a!tget.............................................................................................................................................2$ a!t...................................................................................................................................................2) d!kg................................................................................................................................................2) syna!tic...........................................................................................................................................2) %ailable a!!lications.........................................................................................................................2) 3ice suites – "ord !rocessors4 s!readsheets4 !resentation !ackages...........................................2) P5- ie"ers...................................................................................................................................29 *ra!hics........................................................................................................................................../0 6ail clients.................................................................................................................................../2 7eb Bro"sers.................................................................................................................................// The CHIP 8inu enironent................................................................................................................../ The shell............................................................................................................................................../ The ile syste..................................................................................................................................../$ :ounted ile systes....................................................................................................................../$ -ile !erissions............................................................................................................................../) #isuali;ing the -ile syste............................................................................................................./) Processes.............................................................................................................................................0 &ernel ode s User ode.................................................................................................................2 'oot !riileges and running a!!lications............................................................................................/ :eory anageent.......................................................................................................................... The syss ile syste...........................................................................................................................$ 3!en ile descri!tors...........................................................................................................................$ +yste a!!lications.............................................................................................................................< 7riting your o"n units...................................................................................................................$0 The systedui................................................................................................................................$2 +torage.....................................................................................................................................................$/ Page 2

 =et"orking.......................................................... ....................................................... ..............................$  =et"ork:anager.................................................................. ....................................................... ........$) ........ $)  =et"orking tools............................................................................... ........................................... ................................... ............... .......$, $, iconig net"ork coand.............................................................................................................$, i! net"ork coand......................................................................................................................$, i"conig net"ork coand...........................................................................................................$< i"list net"ork coand.................................................................................................................$< i"conig net"ork coand...........................................................................................................$< ncli...............................................................................................................................................$< "!a>cli............................................................................................................................................$9 "aeon net"ork coand..........................................................................................................$9 'eote login.......................................................................................................................................)0 5oain =ae +erice.........................................................................................................................)0 5=+ +erice 5iscoery and :ulticast 5=+.......................................................................................)2 %ccessing your CHIP ro the Internet.........................................................................................) +haring 7indo"s iles.........................................................................................................................) Creating an access !oint......................................................................................................................),  =et"ork -ile +yste ?=-+@................................................................................. .............................. ..................... ..........)9 .)9 +ockets %PI !rograing...................................................................................................................,1 -inding an IP address ro a hostnae..........................................................................................,1 Creating a socket client...................................................................................................................,2 Creating a socket serer..................................................................................................................,2 +ending data through a socket........................................................................................................,/ 'eceiing data through a socket.....................................................................................................,/ Closing a socket.............................................................................................................................., U5P !rograing.........................................................................................................................., Aaa+cri!t socket.io.............................................................................................................................,$ +ending an eail.................................................................................................................................,$ :TT..................................................................................................................................................,) :TT Protocol..............................................................................................................................,< :osuitto :TT...........................................................................................................................,9 Building osuitto ro source................................................................................................<0 Installing on 7indo"s...............................................................................................................<1 7riting :TT clients....................................................................................................................< 6cli!se !aho...............................................................................................................................< C – :osuitto client library.......................................................................................................<  =ode.Ds Aaa+cri!t – :TT............................................................... ............................... ...................... ................. ........ <) Bro"ser Aaa+cri!t – :TT.....................................................................................................<, 6thernet...............................................................................................................................................90 E7indo"s..............................................................................................................................................90 Using ing on a 7indo"s PC..........................................................................................................91 Using obaEter on a 7indo"s PC..................................................................................................9 Building E a!!lications.......................................................................................................................9, Custoi;ing the E deskto!.................................................................................................................9, 'unning Headless..................................................................................................................................10/ Using your PC as a gra!hical CHIP deskto!.....................................................................................10/ Connecting to CHIP using a serial connection..................................................................................10 Page /

Connecting to CHIP using the U+B cable.........................................................................................10) #=C – #irtual =et"ork Co!uting..................................................................................................10, Prograing..........................................................................................................................................110 Prograing in general....................................................................................................................11/ 68- structure................................................................................................................................11/ 8ibraries o code...........................................................................................................................11 +tatic s 5ynaic libraries......................................................................................................11) Building shared libraries..........................................................................................................11) *eneral deelo!ent tools...........................................................................................................11, ar...............................................................................................................................................11, ldd.............................................................................................................................................11, n.............................................................................................................................................11, obDdu!...................................................................................................................................11< ranlib........................................................................................................................................11< readel.......................................................................................................................................11< C Prograing.................................................................................................................................11<  !kgconig.......................................................... ........................................................ ...................119 ............... ....119 Aaa+cri!t Prograing...................................................................................................................119  =ode.Ds................................................................. ........................................................ ................. ........... ......120 120  =P:............................................................ ....................................................... ......................120 ................ ......120 7riting an =P: odule..........................................................................................................122 Aohnny-ie..................................................................................................................................12/ The Pin obDect..........................................................................................................................12$ I2C "ith Aohnny -ie...............................................................................................................12) CHIP s!eciic Aohnny -ie obDects..........................................................................................12) I2C Co!onent Back!acks......................................................................................................12)  =ode'65............................................................. ........................................................ .................... ............ ........12) 12)  =ode'65 CHIP local installation....................................................... installation....................................................... ........................................12< ................................... .....12<  =ode'65 7indo"s 7indo"s installation...................................................................... ................. ........ ................. ..........12< ..12<  =ode'65 – "riting lo"s................................................................................. ..........................1// ..................... .....1// %danced =ode'65 coniguration.............................................................................................1/ Including additional n! !ackages..............................................................................................1/$ 7riting Custo =ode'65 nodes...............................................................................................1/$  =ode deinition !ro!erties.......................................................................... ............................... ...................... ............1/< ...1/< Installing Custo =ode'65 odules during deelo!ent.......................................................1/9 +haring =ode'65 lo"s.............................................................................................................10 *PI3 "ith =ode'65..................................................................................................................10 +ecurity..................................................................................................................................................11 +ecurity and userids...........................................................................................................................11 %udio......................................................................................................................................................11 U+B attachable audio........................................................................................................................12 8inu %8+% – %danced 8inu +ound %rchitecture........................................................................1/ Pulse Code :odulation.................................................................................................................1/ %8+% !rograing.....................................................................................................................1 %8+% deice enueration.......................................................................................................1) %8+% audio in!ut F ca!ture.....................................................................................................1, %8+% ro Aaa+cri!t.............................................................................................................1, Page 

-reuency +!ectru %naly;er..........................................................................................................1, The libsndile library.........................................................................................................................19 +!eech out!ut....................................................................................................................................1$1 8ogging..................................................................................................................................................1$1 Perorance...........................................................................................................................................1$ 'esource Utili;ation..........................................................................................................................1$ :eory Utili;ation......................................................................................................................1$ Perorance Coands...................................................................................................................1$$ Perorance characteristics o dierent !rograing languages....................................................1$9 Hard"are Interacing.............................................................................................................................1)0 Terinal connections.........................................................................................................................1)0 *PI3 interacing...............................................................................................................................1)2 *PI3 theory..................................................................................................................................1)/ *PI3 on CHIP..............................................................................................................................1)/ *PI3 using libsoc....................................................................................................................1) *PI3 using =ode.Ds.................................................................................................................1)$ I2C.....................................................................................................................................................1)) I2C theory.....................................................................................................................................1)) I2C on CHIP.................................................................................................................................1)9 I2C "ith libsoc.........................................................................................................................1,1 I2C "ith =ode.Ds......................................................................................................................1,2 P7:.................................................................................................................................................1,2 P7: theory.................................................................................................................................1,2 P7: on CHIP..............................................................................................................................1,/ U%'T ?+erial@ Interace....................................................................................................................1,/ U%'T theory................................................................................................................................1,/ U%'T on CHIP.............................................................................................................................1,/ U+B...................................................................................................................................................1, Bluetooth...........................................................................................................................................1,$ Bluetooth s!eciication.................................................................................................................1,$ Bluetooth *%TT.......................................................................................................................1,< +erice 5iscoery Protocol......................................................................................................1,9 Bluetooth C Prograing............................................................................................................1,9 hci>get>route............................................................................................................................1<0 hci>o!en>de...........................................................................................................................1<0 hci>inuiry...............................................................................................................................1<0 hci>read>reote>nae............................................................................................................1<1 str2ba........................................................................................................................................1<1  ba2str.................................................................. ....................................................... ...............1<1 .............. .1<1 Bluetooth %udio............................................................................................................................1<2 Bluetooth '-C3::....................................................................................................................1<2 Bluetooth tools..............................................................................................................................1< l2!ing.......................................................................................................................................1< rco.....................................................................................................................................1<  bluetoothctl............................................................... ............................................. ..................................... ................ ................. ..........1<$ .1<$ hciconig..................................................................................................................................1<) hcitool......................................................................................................................................1<) Page $

gatttool.....................................................................................................................................1<) :icro +5...........................................................................................................................................1<< Hard"are interacing ea!les..............................................................................................................1<< +i!le *PI3 3ut!ut change.............................................................................................................1<9 +i!le *PI3 In!ut change................................................................................................................192 *PI3 etenders.................................................................................................................................19 PC-<$,.......................................................................................................................................19 :CP2/01,....................................................................................................................................19,  =eoPiels................................................................... ........................................................ ................200  =eoPiel theory.............................................................. ............................................ .................................................... ................ ..........200 ..200  =eoPiels on CHIP............................................................... .................................................. ........................................................20/ ......20/  =eoPiels through the %rduino................................................... %rduino................................................... ................................... ........................... ................ .............. ......20/ 20/  =eoPiels through =ode.DsFAohnny-ieF%rduino I2C back!ack........................... ................ ........ ............. .....209 209 8C5 dot atri dis!lay – H5,<0.................................................................................................212 PC-<$, odule..........................................................................................................................21< *P+....................................................................................................................................................220 The g!sd !ackage.........................................................................................................................222 *P+ ro your cell !hone............................................................................................................22, #ideo F 7ebcas...............................................................................................................................22< +treaing a "ebca ideo...........................................................................................................2/1 'ecording a "ebca iage or a !eriod o tie..........................................................................2/1 'ecording a ideo.........................................................................................................................2/2 Playing ideo................................................................................................................................2/2 Barcode and ' Code scanning...................................................................................................2// 3!enC# – 7ebca !rograing................................................................................................2// %nalog to 5igital conersion – %5C0
+ot"are 5eined 'adio – 5#BT 'eceier.....................................................................................2,/ %5+B 5ecoding..........................................................................................................................2, Bluetooth tracker – iTag....................................................................................................................2,, 'eal tie clocks................................................................................................................................2,9 %rduino I56 on CHIP.......................................................................................................................2<2 6lectronics..............................................................................................................................................2
'ecoended !ackages......................................................................................................................../12 Ho" CHIP boots..................................................................................................................................../12 &no"ledge +ources................................................................................................................................/1) Internet 'elay Chat............................................................................................................................/1) 'esearch %reas......................................................................................................................................./1)

Page <

Introduction – The CHIP Book Howdy Folks, I've been working in the software business for over 30 years but until recently, hadn't been playing directly with Micro Processors !hen I bought a "aspberry Pi and then an #rduino, I'$ afraid I got hooked In $y house I a$ surrounded by co$puters of all shapes, si%es and capacities & any one of the$ with orders of $agnitude $ore power than any of these s$all devices & however, I still found $yself fascinated  #s the nu$ber of available single board co$puters continues to grow, HIP caught $y attention #s one of the cheapest on the $arketplace yet re$aining full featured  I had to take a look  and I liked what I found  #s I studied the devices, I started to $ake notes and $y pages of notes continued to grow and grow (his book is $y collated and polished version of those notes "ather than keep the$ to $yself, I offer  the$ to all of us in the HIP co$$unity in the hope that they will be of so$e value My plan is to continue to update this work as we all learn $ore and share what we find in the co$$unity foru$s  #s such, I will re)release the work at regular intervals so please check back at the book's ho$e page for the latest I do not plan on ever calling this book *finished* as there will always be $ore to add +ecause of the breadth and depth of $aterial that we want to cover, it is unlikely that you will want to read the book linearly fro$ cover to cover Instead, I reco$$end that you fa$iliari%e yourself with the table of contents and co$e back to it as and when you need infor$ation  #s you read, $ake sure that you fully understand that there are undoubtedly inaccuracies, errors in $y understanding and errors in $y writing nly by feedback and ti$e will we be able to correct those Please forgive the gra$$atical errors and spelling $istakes that $y spell checker hasn't caught (he ho$e page for the book ishttps-..leanpubco$. chip Please don't e$ail $e directly with technical /uestions Instead, let us use the foru$ and ask and answer the /uestions as a great co$$unity of HIP $inded enthusiasts, hobbyists and professionals

Neil Kolban Texas, USA

Page 9

The CHIP story In May 012, a s$all co$pany called e4t (hing o launched a 5ickstarter pro6ect for a new M7 $odule which they called HIP 8which in this book I 6ust call HIP9 (he goal was to produce a credit)card si%ed :inu4 co$puter for ;< (heir initial ask was ;20,000 to get the pro6ect going (hey received ;,0=1,<=>>> (he 5ickstarter was successfully funded in ?une 012 with 3<,2@0 backers & and fro$ there the challenge was on 5ickstarter backers had to have their early orders fulfilled and pre)orders beyond the 5ickstarter ca$paign were taken I sub$itted an order for  instances of HIP during the first week of ?anuary 01@ and received the$ $id)?uly It is taking a little ti$e, but with patience and perseverance and with the volu$e of HIPs being $ade, it is hoped that their availability should increase (he details of HIP, and how to get the $ost fro$ it is the sub6ect of this book

Introducing the CHIP (he central processing unit 8P79 of the HIP is a 1AH% #llwinner "B processor (here is an on)board 21M+ of "#M and CA+ytes of flash to hold progra$s Fro$ a co$$unications perspective, HIP supports both !iFi and +luetooth C0 Dideo output is supplied in the for$ of co$posite video and hence can be plugged directly into a (D or $onitor that accepts that input for$

(he operating syste$ running on HIP is based on the :inu4 Eebian distribution

Physical architecture (he following i$ages are reproduced fro$ the HIP docu$entation pages (hey illustrate the $a6or co$ponent of the physical structure of the device

Page 10

(he HIP architecture is open source che$atics for HIP can be found on AitHubhttps-..githubco$.e4t(hingo.HIP)Hardware (hird party vendors have build cases for HIP (he following is fro$ C:abs-

e4t(hingo also $ake a ; cover for the rear of the HIP I reco$$end so$e case over the circuitry ooner or later you will put your HIP down on so$ething either wet or $etallic and be disappointed that you shorted so$ething out 8perhaps even da$age the device9

ee also•

Page 11

Gebra HIP ase

CPU (he heart of any co$puter is its P7 HIP uses an #llwinner "B processor running at 1AH% (he architecture of the chip is #r$ orte4)#B ee also•

 #ll!inner "B

•

 #llwinner "B Eatasheet

•

 #llwinner "B 7ser Manual

The storage subsystem HIP co$es with C A+ytes of flash $e$ory for storing data including the operating syste$, your own applications and any data needed by those applications Euring boot, console $essages are written and these can be shown after boot using the * dmesg* co$$and If you were to read through the logs, you would find $ultiple $essages such asBad eraseblock 2034 at 0x0001fcbfc000

(his sounds troubling It see$s to indicate that the storage has errors and this is indeed true Flash $e$ory checks the integrity of data re)flashed and validates that what was written was what was e4pected !hen errors are found, the blocks of storage used to hold data are flagged as invalid and beco$e no longer available for use, thus reducing the overall storage si%e In the current technology available to us, blocks can and do beco$e 8or initially so$e are9 invalid (his is the nature of the high density storage $echanis$s in play (o deter$ine how $any blocks are available and how $any are bad, one can e4a$ine the output of d$esg looking for *bad P+s* For e4a$ple$ dmesg | grep -i "bad PEBs" ubi0 good PEBs 201! bad PEBs 2# corrupted PEBs 0

In the above, we see there are < blocks flagged as *bad* which is about 1C ee also•

ingle +oard "evolution- Preventing flash $e$ory corruption

The power system HIP is powered at 2D and draws about 200$# during boot and other $a4i$al operations with a resting consu$ption of about B0$# (he reco$$endation is to power the device with a 2D supply capable of delivering <00$# or $ore # chip called the #JP0< handles power $anage$ent including the ability to be powered fro$ and charge a :iPo battery n the header ter$inals, we find a variety of power sources include 2D, 33D and 1BD (he $a4i$u$ current draws on these are #, =00$# and 20$# respectively (here is a s$all button on the front of HIP that can be used to switch it on and off If HIP Page 12

is off, then holding the button down for a second will power it on If the HIP is on, then holding the button down for 10 seconds will power it down & however, try and avoid that $ethod (he correct way to shutdown HIP is to run the *sutdo%&* co$$and If we re$ove power fro$ the HIP either by literally re$oving the power or holding the power off button down, then we run the risk of corrupting our device as any files that $ay be in the process of being updates $ay not co$plete and we will end up with corrupt files If we need to supply power to HIP fro$ an e4ternal source 8as opposed to through the 7+9 then we should apply the 2D voltage to the header ter$inals $arked AH)I 8713)9 and AE 8713)1 or 713)C9 (his input arrives at a power regulator If we power the HIP through HA)I, the :Es $ay flash briefly once when power is applied but the HIP not appear to boot (his is as it should be Hold down the power button for 10 seconds and then the :Es will light and HIP boot (he #JP0< is an I device found on I bus 0 at device address 0x34 HIP has two on)board :Es ne is called P'( and is connected directly to a 33D source (his :E is $agenta in color (his $eans that when power is active through the #JP0< 8ie HIP is on9 then the :E will be lit (here is no control over this :E (he second :E is called )*+* and is connected to one of the four API lines 8API9 of the #JP0< (hat $eans that it can be controlled fro$ software (he #JP0< register that controls the signal on API is 0x#3 (his :E is white in color (o switch off the :E, the following I co$$and can be used$ sudo i2cset -f -, 0 0x34 0x#3 0x00

(o switch it back on, we can use$ sudo i2cset -f -, 0 0x34 0x#3 0x01

(he battery connector is a ?()PH  connector +e sure and connect power the right way around Kve is to the right with the 71C header to the left I failed to get this right and i$$ediately fried a precious HIP It $ade $e very sad & please don't $ake the sa$e $istake

able for ?()PH can be purchase very cheaply

Page 1/

:iPo batteries with the correct plugs can also be found

(he #JP0< also has an internal te$perature sensor (he data is available via I by reading registers 0x!E and 0x! fro$ the #JP0< device (he first register is the low order C bits of the result while the second byte is the ne4t B bits & giving us 1 bits in total (o interpret the result, the data is in steps of 01  with a base of )1CC=  #s such, our calculation will be.../alue.0x!e  0x0f  | ../alue.0x!f  0xff  410  14456

(he values of the registers can be read through$ sudo i2cget -, f 0 0x34 0x!e $ sudo i2cget -, f 0 0x34 0x!f

 # script is supplied with :inu4 i$age called *batterysh* !hen run as root, it returns a wealth of infor$ation about the battery subsyste$$ sudo batter,5s B+*7)*+*8)90 :;+(<7=>?91 B+*7E@=)*91 :;+(
Batter, carge curre&t 9 1115!m+ =&ter&al temperature 9 !!52c

HIP $ight be corrupted if we power it down without first shutting down :inu4 #n elegant progra$ is available on AitHub called *blink* that runs as a service at boot ti$e (his progra$ can 8a$ong other things9 detect the button press and cause a clean shutdown to occur eehttps-..githubco$.fordsfords.blink ee also•

 #JP0< Eatasheet

Video output  # 6ack socket is found on HIP into which a supplied cable can be plugged (he cable ter$inates in co$posite video output of audio left, audio right and video

udio output (he 6ack socket used for co$posite video output can also be used for stereo output # standard 32$$ audio plug such as those for headphones or a$plifier input can be inserted

!eyboard input  # 7+ keyboard can be plugged into the 7+ socket (hese can be picked up very cheaply (hinking of the s$all for$ factor of HIP, one of $y favorites is the hand)held wireless keyboards that are available for about ;10);12

(hese devices use a CAH% dongle that plugs into the 7+ port ot only does one get a hand held keyboard, but the $ouse pad at the top works surprisingly well "unning the CC 5ernel i$age, I was delighted to find that it worked first ti$e out of the bo4 with no tweaks or other configurations needed ote that this is not a bluetooth keyboard and hence the dongle needs to be inserted into the 7+ socket onnection to the dongle can be validated by running *lsusb* and looking for the 7+ IE of the dongle$ lsusb Bus 002 ?e/ice 002 =? 2!a60601 Page 1$

Comparison against "aspberry Pi #ero !hen HIP was first $entioned, the closest e/uivalent on the $arket was the ;32 "aspberry Pi  #t over 3 ti$es the price of the proposed HIP and without networking, it see$ed that they would be addressing different $arkets however, in ctober 012, the "aspberry foundation $ade a fantastic announce$ent L the "aspberry Pi Gero (his is also a :inu4 co$puter which is physically s$aller than a credit card with the astonishingly low price of only ;2 I'$ a great fan of choice and co$petition while at the sa$e ti$e not a fan of redundant duplication  I saw the arrival of two very si$ilar devices in a $i4ed light I don't hold a bias on HIP vs "aspberry Pi Gero 8I've written books for both9 :et us try and do as factual a co$parison as possible between the twoConcept

CHIP

Raspberry Pi Zero

Price

9

$

%ailability

Poor ?Auly 201)@

Constrained ?Auly 201)@

Processor

1*H;

1*H;

'%:

$12:B

$12:B

+torage

*Byte lash

:icro +5

7i-i

yes

no

Bluetooth

yes

no

U+B

yes ?Ty!e %@

yes ?:icro@

#ideo

Co!osite

H5:I

*PU su!!ort

=o

Ges

I2C

yes

yes

+PI

no

yes

+erial

yes

yes

%5C

no

no

P7:

no

yes

Caera bus

no

yes

Battery charging

yes

no

3+

8inu

8inu

Counity

-ledgling

:ature

If we co$pare e4clusively on price, obviously ;< is $ore than ;2 but let us not forget that in order to get a Pi Gero running, you will need a Micro E card If you want to network, you will also need a !iFi dongle and since the 7+ port on the Pi Gero is $icro 7+ and the !iFi dongles are 7+ (ype # plugs, you will need an adapter !hile none of these are particularly e4pensive, the additions start to bring the prices in line with each other ee also•

Page 1)

HIP vs Pi Gero- !hich ub);10 o$puter Is +etter

$etting %tarted (o boot up the HIP, we $erely need to supply power to the $icro 7+ power socket HIP will boot and be running HIP co$es supplied with a cable that outputs co$posite video that can be plugged into a (D or $onitors with co$patible inputs Euring booting we will see the :inu4 boot output scrolling by #t the end, we will be presented with a graphical environ$ent with which we can interact #nd now things start to get interesting !e need a $ouse and a keyboard to be connected to allow us to interact ow & this is i$portant & before you start custo$i%ing your HIP you need to ask yourself the /uestion about upgrading the software that is currently on it as shipped fro$ the factory It is likely that what is on the HIP is not the latest and greatest low)level kernels and applications 7nfortunately, we can't yet do an in)place upgrade and $ust re)install the whole i$age in order to get to the latest !hen we do this re)install, #:: configuration changes, applications and data that you place on the HIP is lost If you think you $ight want to go to the latest level, see the section called Flashing new software& before going too $uch further !hen you have started HIP, try hard not to si$ply power it off by re$oving power (hat can corrupt the storage Instead issue the co$$and *sudo sutdo%& &o%* (his will cleanly end the run of the device and after the co$$and has shutdown the device, then you can safely re$ove power fro$ it If you need to restart the device, you can run the co$$and *sudo reboot* (he device will shutdown and then restart Nour HIP doesn't know where in the world it is It will be able to get the universal ti$e fro$ a ti$e server over the internet, but without knowing where in the world you are, it doesn't know your local ti$e %one (o set this up, run the co$$and$ sudo dpkg-reco&figure tCdata

Fro$ there you will be presented with a series of $enus to help you setup your local ti$e%one

&lashing new software (he storage device on HIP is a C A+yte flash $e$ory chip (his is not a re$ovable or replaceable co$ponent !hen new releases of the 5ernel are $ade available, we can install these through a process known as *flashing* It is i$portant to reali%e that flashing the storage results in the co$plete replace$ent of what was there previously +eing very e4plicit, when you flash the HIP, all custo$i%ations, progra$s and data that $ay have been present will be lost and you will be at an e/uivalent of a factory reset to the version of the i$age that you flash (here is no recovery of data that was present before the flashing so $ake sure you copy off any files you $ay want or need to save

Page 1,

(o start understanding how to flash the HIP, visit the website called http-..flashgetchipco$ using a copy of the Aoogle hro$e +rowser (he reason for using hro$e is that the flasher  application used to install the new i$age runs within the hro$e environ$ent nce there, you will see a page si$ilar to the following-

licking the *+?? *D :;(DE* button pops up a confir$ation-

nce added, the page will now show the i$ages that can be flashed onto the HIP-

Page 1<

(he reco$$endation is now to use the *cloud* icon in the upper right of each i$age (his will download the corresponding i$age file (hese files end in *5cp* nce an i$age file has been downloaded, we can find the following i$age to flash this file to the HIP-

(he first ti$e we want to flash, we will see the following dialog-

Page 19

ow we install the driver licking the *I(#:: (H E"ID"* button, downloads an e4ecutable called *=&stall?ri/er25exe* !hen we run this, we get a$ installation wi%ard-

 #s we progress through the wi%ard, the ne4t page seen is-

ow we are ready to flash (o do this, we add a wire fro$ the *EA* ter$inal to a ground Page 20

ter$inal

e4t we plug in HIP to a 7+ port on the P

Page 21

7nfortunately, in $y e4perience, it wasn't that si$ple !hen I plugged it in directly and then followed the later steps, I ended up with failure #fter using a powered 7+ hub, it i$$ediately started working

Page 22

Nou can deter$ine your new currently installed version by running the co$$and$ u&ame -a" Ai&ux cip 454511-&tc F1 )P )at a, 2G 002606 8*: 201H arm/6l <>8Ai&ux

Installing packages nly a subset of the possible available applications are pre)installed on HIP If you want to install $ore, you can (he tools that are available for that are * apt-get* +efore adding new progra$s run apt)get with the * update* flag to refresh the catalog of available applications$ sudo apt-get update

(o upgrade any installed packages, we can use$ sudo apt-get upgrade

(his will deter$ine what you have installed and perfor$ the upgrades to get you to the latest levels of these installed packages Perfor$ing an upgrade can take so$e ti$e so be sure that you are available to leave the HIP running un)attended for a while

Installation tools !hen we think of a :inu4 operating syste$, we will find that the state of a syste$ is governed by the e4istence and versions of files on the file syste$ If we consider a *package* to be a collection of files necessary to perfor$ so$e discrete operation, then we can also think of the files on the :inu4 file syste$ as being $e$bers of so$e package or another 8with the obvious Page 2/

e4ception of application files that you create9 If we wish to install a package, we $ust obtain a copy of all the files associated with that package and place the$ in the correct directories where they are e4pected to be found If we were atte$pt to do this by hand, we would end up in all sorts of troubles ot least of which would be the potentially of $aking $istakes with $anual copies In addition, so$e packages are not self contained but instead have prere/uisites which are the$selves packages !hat we need is so$e registry $echanis$ where we can learn what packages are installed and a repository where packages can be found and downloaded (his is e4actly what the apt technology does for us (he apt technology is a suite of related applications which coordinate together to perfor$ package $anage$ent functions (o begin with, the apt syste$ needs a list of sources fro$ which packages can be found (his is specified in a file called etcaptsources5list It is fro$ this list of sources that new packages and updates to e4isting packages can be found # typical entry in the sources5list file looks likedeb ttpftp5us5debia&5orgdebia& Iessie mai& co&trib &o&-free deb-src ttpftp5us5debia&5orgdebia& Iessie mai& co&trib &o&-free deb ttpsecurit,5debia&5org Iessieupdates mai& co&trib &o&-free deb-src ttpsecurit,5debia&5org Iessieupdates mai& co&trib &o&-free deb ttpttp5debia&5&etdebia& Iessie-backports mai& co&trib &o&-free deb-src ttpttp5debia&5&etdebia& Iessie-backports mai& co&trib &o&-free deb ttpope&source5&extti&g5cocipdebia&repo Iessie mai&deb

It is i$portant to note that a package that is downloaded and installed fro$ the repository $ay not be the very latest version of that package available In fact, e4perience is showing that so$e packages downloaded fro$ the repository are very old indeed e4t we will look at so$e of the pri$ary co$$ands for working with packages (he $ost i$portant of these is apt-get !e will be using apt-get e4tensively to install new packages that aren't present in a default distribution ee also•

apt)rp$org

apt-cache :ist available packages $ apt-cace pkg&ames

how statistics on the cache Pri$arily what we see here is disk space consu$ed by the cache as well as counts of the known packages $ apt-cace stats *otal package &ames !!#11 .111G k *otal package structures !!#1H .2HG4 k Page 2

>ormal packages 43162 Pure /irtual packages H!! )i&gle /irtual packages 44!! ixed /irtual packages !2# issi&g 610! *otal disti&ct /ersio&s 4H#0# .3366 k *otal disti&ct descriptio&s GG!3! .212! k *otal depe&de&cies 2#34G1 .G216 k *otal /erfile relatio&s 4GH16 .66G k *otal ?escile relatio&s GG!3! .1416 k *otal Pro/ides mappi&gs G201 .1H4 k *otal globbed stri&gs 140 .1!34  *otal depe&de&c, /ersio& space 1200 k *otal slack space 6254 k *otal space accou&ted for 1!53 

ee also•

$an8B9 L apt)cache

apt-file (he apt-file tool allows one to find which package $ight contain a specific file ote that apt-file needs to be installed with the following co$$and$ sudo apt-get i&stall apt-file

nce installed, we need to run $ apt-file update

to retrieve the database of packages and the files they contains (o find which package contains a file$ apt-file searc file&ameJ

(o list files contained in a package$ apt-file list package&ameJ

apt-get (he apt)get co$$and is a co$$and line interface to the #dvanced Packaging (ool 8#P(9 library It is by far the $ost co$$only used of the package $anage$ent tools (o install a package we can run$ sudo apt-get i&stall pkg&ameJ

(o un)install a package run$ sudo apt-get purge pkg&ameJ

(o download the package without installing it run$ apt-get do%&load pkg&ameJ

(he downloaded package will end in * 5deb* !e can then install that package using* Page 2$

$ sudo dpkg --i&stall file>ame5debJ

If we 6ust wish to see the effect of perfor$ing a co$$and without actually co$$it to run it, we can add the --simulate option (o refresh our list of packages, we can run$ apt-get update

(o upgrade our installed packages to the latest levels, we can run$ apt-get upgrade

ee also•

$an8B9 L apt)get

•

2 7seful +asic o$$ands of #P()A( and #P()#H for Package Manage$ent

•

:inu4 and 7ni4 apt)get co$$and

apt (o see which packages are installed, run $ apt --i&stalled list

dpkg (he dpkg co$$and is the base co$$and for package installation If we have a local *deb* file which contains a package, we can install it using$ sudo dpkg -i file&ame5debJ

synaptic (here is also a A7I interface to package $anage$ent called *synaptic* (his can be installed through$ sudo apt-get i&stall s,&aptic

ee also•

!ikipedia L ynaptic

'ailable applications (here are hundreds 8thousands9 of installable applications available for HIP Office suites – word processors, spreadsheets, presentation packages  #n e4cellent open source pro6ect called *:ibreffice* is available for HIP :ibreffice is a full function office suite including a word processor, spreadsheet and presentation engine It can Page 2)

be installed through$ sudo apt-get libreoffice

It's a big package and takes a bit of ti$e to install, so be patient and grab a coffee  #fter installation you will find the tools in the *ffice* $enu-

 #t the ti$e of writing the version that is available is *C33* (he word processor provider by :ibreffice is called *!riter* (his book was written on !riter  8on a !indows 10 P I'$ afraid9 Here is what writer looks like-

Page 2,

Dery intuitive and easy to learn (he spreadsheet is called alc and looks like-

Page 2<

 #gain, if you are fa$iliar with other spreadsheets, you will find this one /uick to learn too ee also•

:ibreffice

PDF viewers I often find $yself wanting to read PEF docu$ents on $y HIP # good tool for PEF reading is kular It can be installed with$ sudo apt-get i&stall oklular

(here is /uite a bit to it so it $ay take so$e ti$e to install nce installed, we run$ okular

and open any PEF files we $ay have #s we can see in the following screen shot, a pretty co$prehensive PEF viewer-

Page 29

ee also•

kular ho$e page

Graphics (he A7 I$age Manipulation Progra$ or as it is $ore co$$only called *AIMP* (his can be installed with$ sudo apt-get i&stall gimp

 #fter installation it can be found in the *Araphics* $enu-

Page /0

nce launched, it provides a rich assort$ent of tools for drawing and i$age $anipulation-

Page /1

ee also•

AIMP

Email clients IceEove is a version of the popular Mo%illa (hunderbird e$ail client It can be installed with$ sudo apt-get i&stall icedo/e

IceEove has all the usual features including calendaring and newsfeed support nce installed it can be found under the Internet category-

!hen launched, it looks as follows-

Page /2

e! "rowsers (he popular FireFo4 browser is available

It provides the $a6ority of functions one e4pects fro$ a browser but you will be dissapointed with the perfor$ance co$pared to a P desktop However, that doesn't stop us using it for a variety of purposes including as a kiosk or as a host for browser based applications Page //

The CHIP (inu) en'ironment (he operating syste$ of HIP is :inu4 based on the Eebian distribution (here are $any e4cellent books, web pages and foru$s covering :inu4 so it is not $y atte$pt to try and recreate any of those Instead, here is a very short su$$ary to give you so$e of the core co$$ands and concepts you will find useful and use these as a springboard into further study as needed ee also•

!iki pedia L :inu4

The shell !ithout e4ception, an environ$ent on HIP that you will be working with is the shell (he shell is a co$$and interpreter that takes the co$$ands you enter at the keyboard and e4ecutes the$ !hether you use the *ss* progra$ to re$otely login or start a ter$inal e$ulator on the graphical desktop, both present you with an instance of the shell !hen you enter a co$$and, the co$$and is looked for in each of the directories specified Page /

by the P+*; environ$ent variable (he first directory which contains a file with the na$e of your co$$and is the one that is e4ecuted Nou can see a history of your previous co$$ands by entering * istor,* # list of co$$ands prefi4ed by a nu$ber is displayed ntering *K&umJ* will cause that co$$and to be re)e4ecuted

The file system (he HIP file syste$ is a standard :inu4 file syste$ hosted in flash $e$ory (his is a hierarchical file)syste$ co$prised of files and directories It supports all the standard :inu4 co$$ands for file $anipulation-

•

cp L copy files

•

m/ L $ove files

•

rm L re$ove files

•

ls L list files

•

l& L link files

•

mkdir L $ake a directory

•

rmdir L re$ove a directory

•

cmod L change file and directory per$issions

•

mou&t L $ount a file syste$ for use

•

umou&t L un)$ount a previously $ounted file syste$

ee also•

$an819 L ln

#ounted file systems HIP supports the standard 7ni4 *mou&t* co$$and for $ounting file syste$s onto the file structure #n especially useful co$$and is called *fi&dm&t* that displays a visuali%ation of what is $ounted and where

ee also•

Page /$

$an8B9 ) find$nt

File permissions n a :inu4 , files and directories have per$issions associated with the$ +y and large there are three per$issions a file can have which are *read*, *write* and *e4ecute* (hese declare whether a file can be read fro$, written to or be e4ecuted # file also has the concept of an owner and a group !hen we talk about per$issions, we further categori%e the per$issions into those that are allowed for the owner of the file, those that are allowed for $e$bers of the group associated with the file and those that are allowed for everyone else 8ie neither the owner nor a $e$ber of the group9

!e thus end up with nine specific per$issions-

•

owner L read . write . e4ecute

•

group $e$ber L read . write . e4ecute

•

others L read . write . e4ecute

 #n encoding sche$e has been used for visuali%ing and describing per$issions for files using the octal nu$bering syste$ 8base B9 If we i$agine that the three per$issions were described in 3 bit binary with an order of read . write . e4ecute then we would have per$issions of *r%x* & or O1.0O1.0O1.0 o in binary, per$issions of 101 would say we have per$ission to read and e4ecute but not write If we translate this binary into octal, it would be written as CK0K1 Q 2 (hus we can represent a set of read . write . e4ecute per$issions as a single octal digit 80)=9 o$bining this with the notion that we have three sets of per$issions 8user, group and other9, we can co$pletely describe all the per$issions on a file with three octal digits For e4a$ple =22 would be a value of = for user 8read . write . e4ecute9 and 2 for both group and other 8read . e4ecute9 (he :inu4 co$$and called cmod can be used to set the per$issions For e4a$plecmod 6!! m,ile

Eoes this sound co$plicated Nes it does & however it is how 7ni4 has been handled since its inception (here are other $echanis$s should you not wish to re$e$ber these encodings and those can be read about in the $an pages for cmod

$isuali%ing the File system For those who don't want to navigate through the file syste$ fro$ the shell, there is an attractive A7I navigator supplied by the tool called *(hunar*

Page /)

(his can be started fro$ the desktop conte4t $enu by running * ile a&ager* (he feel of this is si$ilar to the Microsoft !indows 4plorer environ$ent I'll assu$e that $ost of us are fa$iliar with navigating a file $anager like this but here are so$e of the $ore interesting features  #nother popular file $anager is called *autilus* (his is also provided on HIP It looks as follows-

 # third file $anager is called *PManFM* however this is not installed by default !e can install it using$ sudo apt-get-i&stall pcma&fm Page /,

(his is the file $anager used by default on the "aspberry Pi "aspbian operating syste$ so if you are $oving fro$ a Pi environ$ent to HIP, this $ay be an attractive choice (his can be started fro$ the co$$and line tool * pcma&fm* or fro$ the icon in the task bar (he feel of this is si$ilar to the !indows 4plorer environ$ent I'll assu$e that $ost of us are fa$iliar with navigating a file $anager like this but here are so$e of the $ore interesting features First there is a dual pane $ode 8Diew J Eual Pane Mode . F39 (he screen splits into two parallel views where you can look at two distinct folders Fro$ here you can drag and drop files between the$

o$eti$es the large icon view is distracting and you can switch to a detail view 8Diew Folder Diew Mode J Eetailed :ist Diew9-

Page /<

J

r you can go so$ewhere in between with the co$pact view-

Nou can open $ultiple tabs where each tab is its own folder view 8File

J ew

(ab . (":K(9

Possibly one of the $ost i$portant functions is the ability to open a shell window at the current folder !e can do this fro$ (ools J pen urrent Folder in (er$inal . FC  #n especially elegant feature in this package is the ability to *book$ark* fre/uently used folders nce book$arked, it appears on the list on the length and provides a /uick Page /9

navigation to that folder when needed (he choice of which one you use is purely personal preference (o choose the default in use, open up the *)etti&gs a&ager* and select *Preferred +pplicatio&s*-

In the 7tilities section, we will find an entry called * ile a&ager* where we can specify which of the available File Manager packages we want to use-

 #n alternative to the graphic environ$ent is the tool called * tree* which visuali%es a directory structure as an #II tree layout (his progra$ is not installed by default and one $ust install using$ sudo apt-get i&stall tree

ee also•

!ikipedia L (hunar 

•

!ikipedia L autulius 8AM Files9

•

PManFM L File $anager 

Processes  # process is the na$e we give to a running instance of a progra$ !hen we start a progra$ it runs within its own conte4t separate fro$ the conte4t of other progra$s (he process Page 0

$anages that conte4t and includes the files that progra$ opened, the e4ecutable running, the environ$ent variables, the user running the progra$ and $ore ach process is uni/ue identified with an integer identifier call the Process IE or PIE (o see which processes are running on our HIP we can issue the * ps* co$$and (his has a ferocious nu$ber of options and deep reading of the $anual page would be re/uired to gain full appreciation In its basic for$, when we run it it will show the PIE and co$$and associated with that pid For  e4a$ple$ ps P=? **L 6232 pts1 66!6 pts1

*=E :? 000000 bas 000000 ps

otice that we get to see the PIE colu$n #nother co$$and available to us is called *pidof* (his takes the na$e of a co$$and and returns us the PIEs for all instances of that co$$and For e4a$ple$ pidof gea&, 4G23

nce we know the PIE of a running progra$, we can ter$inate it by sending it a * kill* signal (hese are asynchronously trans$itted signals that indicate to the process that so$e e4ternal event has happened (o see the list of possible signals run$ bi&kill -A 1 ;8P 2 =>* G PE # N=AA 1! *E( 1H )*NA* 22 **D8 23 8(< 2# PDAA 30 P'(

3 10 16 24 31

M8=* 8)(1 :;A? @:P8 )L)

4 11 1G 2!

=AA )E< :D>* @)O

! 12 1# 2H

*(+P 8)(2 )*DP *+A(

H 13 20 26

+B(* P=PE *)*P P(D

6 14 21 2G

B8) +A( **=> '=>:;

(o send a signal we can use one of the following two synta4 for$atskill -&umberJ P=?J

or  kill -&ameJ P=?

For e4a$plekill -1 4G23

and kill -;8P 4G23

are identical ach signal can be trapped by the process that receives it allowing the process to deter$ine how it wishes to handle its arrival (he one e4ception is .# N=AA & which is un)trapable and causes the i$$ediate ter$ination of the process (he way that a new process is created is through a techni/ue called *forking* (here is a low level syste$ call na$ed fork. that, when e4ecuted, causes a brand new instance of the original process to be created (he new instance shares everything fro$ the first one including open files, variable values, environ$ent variables & everything (he difference between the$ is that the return code fro$ fork. call for the original process is the process id for the new process while the new process receives a value of 0 In the new forked Page 1

process, it is then very co$$on for a second syste$ call to be $ade called exec. !hat this does is load a new e4ecutable into the address space of the e4isting process 8the forked copy9 and begin its e4ecution If this feels a trifle convoluted, I can't argue with that & however it does provide a $echanis$ for a newly started process to inherit the environ$ent of the starter which can include aspects such as current userid, group $e$bership, open files and $ore #nd that is a desirable situation !hen we run a new shell co$$and, that also causes a new process to run (he shell starts the process and then waits for it to co$plete If we don't wish to wait, we can run it in the background by adding an ** to the end of the co$$and For e4a$ple, running$ gea&, m,file5c 

causes the geany editor to open.create a file and i$$ediately detaches it fro$ the starting ter$inal allowing us to run additional co$$ands in that ter$inal Fro$ within a  progra$, we can also start another process by using the s,stem. call (his takes the file syste$ path of an e4ecutable and starts it while waiting for it to co$plete (his is a /uick way of perfor$ing work by letting sub)progra$s do co$ple4 6obs for us For e4a$ple, should we wish to play a sound, we can call apla,. to play the sound through the s,stem. call ee also•

$an819 L ps

!ernel mode 's User mode (he :inu4 operating syste$ is designed to support both $ultiple users and $ultiple processes si$ultaneously ne of the i$plications of this is that a badly written or $alfunctioning application should not be able to negatively i$pact the activities of either other users or other processes (he way this is achieved is through the separation of kernel level functions and user code level functions ach process runs in its own address space with isolation fro$ each of the others (his $eans that it is difficult for one application to da$age the $e$ory of another However, I. operations are co$$on between applications Most have to read and write fro$ files for e4a$ple o$ewhere in the operating syste$ there has to be code that interacts at a low level with the disks If the disks could be accessed fro$ user application code, then that could da$age the$ or co$pro$ise security #s such, access to I. is considered a privileged operation and should only be perfor$ed by trusted code #nd this is where the 5ernel co$es into play ode running on a :inu4 $achine can *run within the 5ernel* (his $eans that it is trusted code that runs with the $ost privileges It also has full access to all the internal data structures that are used to $aintain the operating syste$ as a whole 5ernel code can also run at higher level priorities than other code In nor$al HIP progra$$ing, you will be unlikely to be writing any new code that will be e4ecuting within the 5ernel however you will be leveraging $any functions that interface with HIP hardware and access to these will be through HIP specific 5ernel $odules that have been supplied Page 2

"oot pri'ileges and running applications :inu4 is a $ulti)user operating syste$ (his $eans that $ultiple distinct users can si$ultaneously login to a single syste$ and run applications concurrently with each other It is not desirable for one user to be able to read the files fro$ another and hence there are per$ission capabilities associated with each individual user However, there is a special user in a :inu4 syste$ that is called *root* (his user is also know as the *superuser* "oot is not constrained by nor$al security constraints "oot can ter$inate any process and read.write to any file #s such, root is nor$ally given only to the $ost trusted syste$ ad$inistrators and ordinary users run with their ordinary userids However, on the HIP, there are ti$es when we wish to access hardware or run powerful co$$ands 8anything that affects the syste$ as a whole is usually considered to be under this category9 # special co$$and is supplied called *sudo* that takes as a para$eter another co$$and to run (hat second co$$and is then e4ecuted with root per$issions ffectively, it escalates the privileges of the co$$and to root  6ust for the duration of that process  # /uestion that arises fro$ ti$e to ti$e is that we know that the default userid is * cip* with a password of *cip*, what then is the default password for * root* (he answer is that there is none and by that we $ean that login as root is disabled If you want to beco$e root, then run$ sudo -i

n occasion there is discussion in the foru$s on the correctness of having to run so$e user written HIP applications as root n a production, $ulti)user operating syste$, I wouldn't /uestion that notion but I $aintain that the HIP is not that ince I can't i$agine a HIP user not knowing the root password or being allowed to run sudo, the HIP is already co$pro$ised fro$ a $ulti)user perspective Fro$ a syste$ stability point of view, any progra$ that runs as root can potentially destroy the syste$ #s such, take back)ups of your Page /

syste$ as needed so that you have a restore point In $y e4perience, I have yet to $ake such a serious accidental error that $y syste$ has been destroyed (he sudo co$$and is governed by a * etcsudoers* file which lists the users that are authori%ed to elevate their per$issions via sudo (o add a user to the set of sudo authori%ed users, we can runadduser user&ameJ sudo

(his will add the user to the * sudo* group and $e$bers of that group are authori%ed to run sudo #fter the change, the user $ust logout and log back in again for the change to take effect ee also•

ecurity and userids

*emory management In a :inu4 environ$ent, each application sees its own address as a virtual address space (hey believe that they are alone in $e$ory and the operating syste$ takes care of $apping the application addresses to the real $e$ory addresses ince HIP has a 21M+ytes of "#M, this would see$ to i$ply that the $a4i$u$ nu$ber of progra$s that HIP can run is constrained (he operating syste$ and related co$ponents use so$e "#M and then there is the cost for running each of your own applications in parallel In $ost :inu4 syste$s, there is the concept of swap space on disk !hat that $eans is that should we start to run low on available "#M, applications that haven't touched $e$ory in a while can have so$e or all of their allocationw written to disk (his is called paging (he data that was in "#M isn't lost  its safely stored on disk and hence can be recovered  however the space used by what is now on disk is available for re)use hould the original application need the $e$ory again, the operating syste$ will re)load the $e$ory, swapping it out with so$e other progra$s allocation if needed ow we need to re$e$ber that there isn't actually a disk on HIP, instead we have flash $e$ory !hile in principle, we could swap $e$ory to flash, that is a really bad practice !hen the operating syste$ is perfor$ing swap operations, it is potentially reading and writing lots and lots data !hile flash is great, it does *wear* and the a$ount of data being $oved for   swapping would 6ust cause it to wear that $uch faster (o list the processes sorted by their $e$ory usage, we can use$ ps aux% sort9-/sC

or  $ ps aux% sort9-mem

ee also•

Page 

Me$ory 7tili%ation

The sysfs file system In the :inu4 world, a guiding principle is that everything can be considered a file on the file syste$ If we look in the de/ directory we will see entries for ter$inals, serial ports, printers and video input devices Most of these have physical counterparts and access is /uite si$ple  we read and write and are done +ut what of $ore subtle interactions such as I, P!M, or API :inu4 has added a concept that is a virtual file syste$ called *sysfs* (his file syste$ is i$ple$ented in the  kernel and provides a bridge fro$ user applications 8applications that run in *user space*9 to the drivers in the kernel for the co$ponents in /uestion n HIP, the file syste$ is auto$atically $ounted at s,s  #t the highest level we haves,s |-|-|-|-|-|-|-|-|-Q--

block bus class de/ de/ices firm%are fs ker&el module po%er

(he structure is not arbitrary and the locations and na$es of the files and directories have $eanings

•

block L ntries for block oriented devices

•

bus L ntries for data buses (his includes I and PI For each entry in bus, that directory itself contains two directories called * de/ices* and *dri/ers*◦ de/ices L #n entry for each device connected to that bus ◦ dri/ers L Erivers associated with the bus

•

class L ntries for devices by class

•

de/ices L ntries for each known device

ee also•

!ikipedia L sysfs

•

(he sysfs Filesyste$

•

API on HIP

+pen file descriptors  #l$ost everything in :inu4 is based around the notion of a file !hether that files is a real file Page $

on the file syste$ or a si$ply a file descriptor of an opened physical device, fro$ the "aspbian process perspective, it is a file descriptor ince these are owned and $anaged by the kernel itself, there is the possibility of using a tool to show us what file descriptors a process has open or, conversely, look at a device or file and ask what processes have it open (he tool in /uestion is called * lsof* It is not installed by default so it $ust be $anually installed fro$ the * lsof* package$ sudo apt-get i&stall lsof

(his co$$and has a deep richness of options and great study of the $an page would be needed to understand all the possibilities However, there are so$e co$$on recipes that one can use without knowing too $uch additional details Here is a recipe that shows which processes have a particular file open $ sudo lsof :D+>? P=? agett, H34 agett, H34 agett, H34

de/tt,1 8)E( ? root 0u root 1u root 2u

*LPE ?E=:E )=OED >D?E >+E :;( 41 0t0 1042 tt,1 :;( 41 0t0 1042 tt,1 :;( 41 0t0 1042 tt,1

!hen it co$es to networking, lsof is again e4tre$ely valuable (he pri$ary (P.IP networking #PI is called sockets and uses file descriptors as the $eans of $aintaining conte4t for a connection "unning *sudo lsof -i* lists the socket do$ain protocols $ sudo lsof -i :D+>? P=? rpcbi&d 2G2 rpcbi&d 2G2 rpcbi&d 2G2 rpcbi&d 2G2 rpcbi&d 2G2 rpcbi&d 2G2 rpc5statd 2#1 rpc5statd 2#1 rpc5statd 2#1 rpc5statd 2#1 rpc5statd 2#1 ssd 30G ssd 30G a/ai-dae 322 a/ai-dae 322 a/ai-dae 322 a/ai-dae 322 &tpd 3#0 &tpd 3#0 &tpd 3#0 &tpd 3#0 &tpd 3#0 &tpd 3#0 &tpd 3#0 &tpd 3#0 d&smasU 404 d&smasU 404 d&smasU 404 d&smasU 404 d&smasU 404 Page )

8)E( root root root root root root statd statd statd statd statd root root a/ai a/ai a/ai a/ai &tp &tp &tp &tp &tp &tp &tp &tp d&smasU d&smasU d&smasU d&smasU d&smasU

? Hu 6u Gu #u 10u 11u !u Gu #u 10u 11u 3u 4u 12u 13u 14u 1!u 1Hu 16u 1Gu 1#u 20u 21u 2!u 2Hu 4u Hu 6u Gu #u

*LPE ?E=:E )=OED >D?E >+E =P/4 !2H# 0t0 8?P Rsu&rpc =P/4 !262 0t0 8?P RGG1 =P/4 !263 0t0 *:P Rsu&rpc .A=)*E> =P/H !264 0t0 8?P Rsu&rpc =P/H !26! 0t0 8?P RGG1 =P/H !26H 0t0 *:P Rsu&rpc .A=)*E> =P/4 !3H4 0t0 8?P cip1G#1 =P/4 !361 0t0 8?P R!61#H =P/4 !364 0t0 *:P R4H133 .A=)*E> =P/H !366 0t0 8?P R3#!40 =P/H !3G0 0t0 *:P R4#G60 .A=)*E> =P/4 G3G1 0t0 *:P Rss .A=)*E> =P/H G3G3 0t0 *:P Rss .A=)*E> =P/4 H22# 0t0 8?P Rmd&s =P/H H32# 0t0 8?P Rmd&s =P/4 H331 0t0 8?P R4H34# =P/H H332 0t0 8?P R!22G6 =P/4 H!#0 0t0 8?P R&tp =P/H H!#1 0t0 8?P R&tp =P/4 HHG# 0t0 8?P cip1&tp =P/4 HH#0 0t0 8?P 1625205051&tp =P/H HH#1 0t0 8?P localost&tp =P/H HH#2 0t0 8?P SfeG0cc6#cffffe21db#!T&tp =P/4 G001 0t0 8?P 1#251HG51510#&tp =P/H G002 0t0 8?P SfeG0ce6#cffffe21db#!T&tp =P/4 HH#G 0t0 8?P Rbootps =P/4 H601 0t0 8?P Rdomai& =P/4 H602 0t0 *:P Rdomai& .A=)*E> =P/H H603 0t0 8?P Rdomai& =P/H H604 0t0 *:P Rdomai& .A=)*E>

ssd 66G root 3u =P/4 J1#251HG5152004#612 .E)*+BA=);E? ssd 6G3 root 3u =P/4 J1#251HG5152004#613 .E)*+BA=);E? ssd 6#1 cip 3u =P/4 J1#251HG5152004#612 .E)*+BA=);E? ssd 6#1 cip 10u =P/H ssd 6#1 cip 11u =P/4 ssd 6#1 cip 13u =P/H .E)*+BA=);E? ssd 6#1 cip 1Hu =P/H .E)*+BA=);E? ssd 6#1 cip 16u =P/H .E)*+BA=);E? ssd 6#1 cip 1Gu =P/H .E)*+BA=);E? ssd 6#1 cip 1#u =P/H .E)*+BA=);E? ssd 6#1 cip 20u =P/H .E)*+BA=);E? ssd 6#1 cip 21u =P/H .E)*+BA=);E? ssd 6#1 cip 22u =P/H .E)*+BA=);E? ssd 6#1 cip 23u =P/H .E)*+BA=);E? ssd 6#1 cip 24u =P/H .E)*+BA=);E? ssd 6#1 cip 2!u =P/H .E)*+BA=);E? ssd 6#1 cip 2Hu =P/H .E)*+BA=);E? ssd 6#1 cip 26u =P/H .E)*+BA=);E? ssd 6#1 cip 2Gu =P/H .E)*+BA=);E? ssd 6#1 cip 30u =P/H .E)*+BA=);E? ssd 6#1 cip 31u =P/H .E)*+BA=);E? ssd 6#1 cip 32u =P/H .E)*+BA=);E? ssd 6#1 cip 33u =P/H .E)*+BA=);E? ssd 6#6 cip 3u =P/4 J1#251HG5152004#613 .E)*+BA=);E? xfce4-ses G0G cip 3u =P/H .E)*+BA=);E? dbus-lau& G11 cip 3u =P/H .E)*+BA=);E? dbus-lau& G11 cip 4u =P/H .E)*+BA=);E? xf%m4 G20 cip 3u =P/H .E)*+BA=);E? xfce4-pa& G24 cip 3u =P/H .E)*+BA=);E? *u&ar G2H cip 3u =P/H .E)*+BA=);E? xfdesktop G2G cip 3u =P/H .E)*+BA=);E? Page ,

#000

0t0

*:P 1#251HG51510#ss-

#03G

0t0

*:P 1#251HG51510#ss-

#000

0t0

*:P 1#251HG51510#ss-

#21# #220 #2!1

0t0 0t0 0t0

*:P localostH010 .A=)*E> *:P cip1H010 .A=)*E> *:P localostH010-Jlocalost3H#60

#2H#

0t0

*:P localostH010-Jlocalost3H#62

#26H

0t0

*:P localostH010-Jlocalost3H#64

#341

0t0

*:P localostH010-Jlocalost3H#6H

#34G

0t0

*:P localostH010-Jlocalost3H#6G

#3#1

0t0

*:P localostH010-Jlocalost3H#G0

#4H4

0t0

*:P localostH010-Jlocalost3H#G2

#462

0t0

*:P localostH010-Jlocalost3H#G4

#H22

0t0

*:P localostH010-Jlocalost36002

#!0G

0t0

*:P localostH010-Jlocalost3H#GG

#!13

0t0

*:P localostH010-Jlocalost3H##0

111!H

0t0

*:P localostH010-Jlocalost3604H

#H44

0t0

*:P localostH010-Jlocalost3600G

#H0#

0t0

*:P localostH010-Jlocalost36000

102G0

0t0

*:P localostH010-Jlocalost36020

#H61

0t0

*:P localostH010-Jlocalost36012

#644

0t0

*:P localostH010-Jlocalost36014

114!!

0t0

*:P localostH010-Jlocalost3610G

#03G

0t0

*:P 1#251HG51510#ss-

#26!

0t0

*:P localost3H#64-JlocalostH010

#2!0

0t0

*:P localost3H#60-JlocalostH010

#2HG

0t0

*:P localost3H#62-JlocalostH010

#340

0t0

*:P localost3H#6H-JlocalostH010

#3#0

0t0

*:P localost3H#G0-JlocalostH010

#461

0t0

*:P localost3H#G4-JlocalostH010

#4H3

0t0

*:P localost3H#G2-JlocalostH010

/olti G30 .E)*+BA=);E? bluema&-a G34 .E)*+BA=);E? pk-update G3G .E)*+BA=);E? &m-applet G40 .E)*+BA=);E? xfce4-po% G41 .E)*+BA=);E? polkit-g& G43 .E)*+BA=);E? xfsetti&g G44 .E)*+BA=);E? pa&el-H-s G!0 .E)*+BA=);E? xfce4-ter #3H .E)*+BA=);E? gea&, 10#1 .E)*+BA=);E? &ode 1141 &autilus 11!2 .E)*+BA=);E?

cip

!u

=P/H

#H43

0t0

*:P localost3600G-JlocalostH010

cip

4u

=P/H

#640

0t0

*:P localost36014-JlocalostH010

cip

3u

=P/H

#!12

0t0

*:P localost3H##0-JlocalostH010

cip

4u

=P/H

#H21

0t0

*:P localost36002-JlocalostH010

cip

3u

=P/H

#!06

0t0

*:P localost3H#GG-JlocalostH010

cip

3u

=P/H

#H0G

0t0

*:P localost36000-JlocalostH010

cip

3u

=P/H

#346

0t0

*:P localost3H#6G-JlocalostH010

cip

3u

=P/H

#H60

0t0

*:P localost36012-JlocalostH010

cip

4u

=P/H

1026#

0t0

*:P localost36020-JlocalostH010

cip

3u

=P/H

111!!

0t0

*:P localost3604H-JlocalostH010

cip cip

11u Gu

=P/H =P/H

113#2 114!4

0t0 0t0

*:P R3000 .A=)*E> *:P localost3610G-JlocalostH010

(his co$$and is particularly useful is you are writing server applications and so$e other process already has the port you want to listen upon open Nou can use *lsof* to deter$ine which process that $ight be (o filter the results we can use the * -ifilter specJ* where the filter specification isS4HTSprotocolTSVost&ame|V=P +ddressTSser/ice|portT

•

4H L ither C for (P.IP vC or @ for (P.IP v@

•

Vost&ame L (he hostna$e of the partner 

•

V=P +ddress L (he IP address of the partner 

•

ser/ice L (he (P.IP service na$e

•

port L (he (P.IP port nu$ber 

For e4a$ple, to see what processes are using the web server port$ lsof -iG0 :D+>? P=? 8)E( apace2 H41 root apace2 342H %%%-data apace2 3426 %%%-data

? 3u 3u 3u

*LPE ?E=:E )=OED >D?E >+E =P/H G62# 0t0 *:P Rttp .A=)*E> =P/H G62# 0t0 *:P Rttp .A=)*E> =P/H G62# 0t0 *:P Rttp .A=)*E>

ee also•

$an8B9 L lsof 

%ystem applications !hen :inu4 starts, it needs to know which services it needs to also start 4a$ples of Page <

services would be de$ons such as web servers, F servers and $ore (he package called s,stemd provides $anage$ent of such re/uests (o see the list of units defined we can run$ s,stemctl list-u&its

(his not only shows the defined units but their status (he colu$ns shown include-

•

7I( L (he na$e of the unit

•

:#E

•  #(ID •

7+

•

E"IP(I L # description of the unit

!e can /ualify the list-u&its co$$and with a --t,pe9t,peJ flag to filter on 6ust specific types of units For e4a$ple$ s,stemctl list-u&its --t,pe9ser/ice

:ists all the units that are services If we want to see a graph of the units that are enabled we can run$ s,stemctl status

(o see the status of a specific service we can add the service na$e$ s,stemctl status ser/ice &ameJ

(his last co$$and will also show the script used to start the service (o start a service we can run$ sudo s,stemctl start ser/ice &ameJ

(o stop a service we can run$ sudo s,stemctl stop ser/ice &ameJ

and to restart a service we can run$ sudo s,stemctl restart ser/ice &ameJ

o$e services allow us to reload their configurations with$ sudo s,stemctl reload ser/ice &ameJ

(he details of what a particular unit is going to do when started or stopped can be found by running$ s,stemctl cat ser/ice &ameJ

(his will log the content of the unit configuration file ee also•

syste$d yste$ and ervice Manager 

•

yste$d ssentials- !orking with ervices, 7nits, and the ?ournal

Page 9

•

7nderstanding and 7sing yste$d

•

Nou(ube- (utorial L syste$d +asics

riting your own units ince s,stemd runs against units and we can write our own units to control our own applications, let us start on that 6ourney (he core locations for units are etcs,temds,stem and usrlibs,stemds,stem

:et us take apart an e4isting unit so that we $ay see what it looks like !ithin etcs,stemds,stem we will find a file called * ssd5ser/ice* If we look within we will find the followingS8&itT ?escriptio&9Dpe&B)? )ecure )ell ser/er +fter9&et%ork5target auditd5ser/ice :o&ditio&PatExists9Ketcssssd7&ot7to7be7ru& S)er/iceT E&/iro&me&tile9-etcdefaultss Exec)tart9usrsbi&ssd -? $));?7DP*) Exec(eload9bi&kill -;8P $+=>P=? Nillode9process (estart9o&-failure S=&stallT 'a&tedB,9multi-user5target +lias9ssd5ser/ice

 #t a high level, a configuration file is co$posed of a series of sections with the section na$e in s/uare brackets Following those are a series of &ame9/alue properties for the corresponding section  #$ongst the sections we have-

•

O7nit

•

Oervice

•

OInstall

For the S8&itT section we will invariably wish to include a Eescription line that provides an nglish description of what the unit $eans For e4a$pleS8&itT ?escriptio&9, ser/ice tat does @LO

In the S)er/iceT section, here we describe how to start a particular service (here are $any possible options here and we will touch on 6ust a few (he first is the *,pe line (his describes how the service will be started (he value of simple $eans that s,stemd will si$ply fork. and exec. the service (his is co$$only 6ust what we want # value of forki&g $eans that again s,stemd will fork. and exec. the service but that service will itself fork. and exec. other instances e4t we have the Exec)tart line (his is Page $0

vital (his specifies the path and para$eters that will be used to start the service (he 'orki&g?irector, line 8if present9 specifies the directory that will be the working directory for the newly started service (he 8ser line is used to na$e a local :inu4 user that the service will run as  #fter having edited a unit file, we $ust run s,stemctl daemo&-reload to cause s,stemd to re)scan its configuration files and unit files $ sudo s,stemctl daemo&-reload

For e4a$ple if we create etcs,stemds,stemtest)er/ice5ser/ice containingS)er/iceT *,pe9simple 8ser9pi 'orki&g?irector,9omepisrcproIectstest)er/ice Exec)tart9usrlocalbi&&ode test)er/ice5Is

ow when we wish to start the service, we can issue$ sudo s,stemctl start test)er/ice

!hich will cause the service to be started Hopefully now you $ay get an RahaS $o$ent !hat this $eans is that for each service defined, we as ad$inistrators of our HIP :inu4  no longer have to re$e$ber $echanics of how to start dae$ons #ll we need to know is their  logical service na$e and issue a start co$$and +ut what if we want to stop a service i$ply issuing$ sudo s,stemctl stop test)er/ice

will stop it +y default, the way that s,stemd perfor$s that task is to e4ecute a kill against the previously re$e$bered process id of the start re/uest If we have an alternate shutdown procedure, we can define another state$ent in our S)er/iceT section called Exec)top (his co$$and should stop the previously started service in whatever clean $anner is possible # special variable called $+=>P=? is $ade available to the co$$and which is the process Id of the previously started service !e have now touched upon what it takes to start and stop a service $anually, but what if we want the service to start auto$atically !e can again do this with s,stemd but it takes a little $ore consideration (he first thing to reali%e is that services typically depend on each other For e4a$ple, there is no point in starting the e)$ail processing service until and unless the network services have already been started !e can define relationships between units with additional state$ents in the S8&itT section (he first one we will touch upon is the (eUuires state$ent (his na$es additional units which should also be started when the current unit is started !e also have the state$ents Before and +fter (hese define the relative order in which $ultiple 7nits should be started For e4a$ple if we haveS8&itT (eUuires9x,C5ser/ice +fter9x,C5ser/ice

then we have declared that when this current unit is started we had better also start the x,C5ser/ice but it $ust be started after x,C5ser/ice has in fact started Page $1

For e4a$ple, if we wish our service to start but only after we have networking available, we $ight codeS8&itT +fter9&et%ork-o&li&e5target

(here are other state$ents that are si$ilar to (eUuires but with slightly altered se$antics (eUuires states that if a dependent unit fails to start then so do we (he 'a&ts state$ent again lists units to be started but should they fail, then our unit will still be allowed to start If we wish to auto$ate the start)up of a service, in the 7nit file for that service we should add an S=&stallT section (his will include a * 'a&tedB,* entry which will list the unit that, if it is started will also start our new unit # good e4a$ple would be * multi-user5target* For e4a$ple, S=&stallT 'a&tedB,9multi-user5target

ee also•

$an L syste$dservice

&he systemd-ui  # graphical user interface is available for s,stemd operations It can be installed fro$ the s,stemd-ui package using$ sudo apt-get i&stall s,stemd-ui

(he launcher co$$and is$ sudo -E s,stemadm

Page $2

%torage Nour HIP uses flash $e$ory for storing data (he HIP has a CA+yte flash chip built in (his storage holds the operating syste$, your installed applications and data that your applications need ow CA+ytes see$s like a lot but co$pared to a P which $ight have hundreds of A+ytes 8or even a terabyte or $ore9, it isn't huge However it is $ore than sufficient for the $a6ority of tasks we will need to perfor$ +efore you start working on your HIP and creating new files, so$e words of caution and so$e suggestions ince the HIP storage is physically wired flash $e$ory as opposed to a re$ovable storage $ediu$ such as $icro E $e$ory cards, if your HIP device beco$es da$aged or broken, you $ay never be able to retrieve your data fro$ the device (hink about that for a $o$ent I$agine you have spent weeks or $onths writing an application to run on HIP and the source code to your app resides on the file syste$ contained in the flash $e$ory of the HIP ow you find that your HIP no longer boots and a sinking feeling co$es over you bviously, good practice is to take backups regularly however, few of us do $ake those backups as often as we should If we weren't using HIP but using a single board co$puter with re$ovable storage 8eg a "aspberry PI9, we could also get ourselves a new device and re$ove the storage fro$ the now defunct syste$ and place it in the new syste$ and we are back up and running !e can't do that with HIP I do a lot of progra$$ing and if I were to lose $y data I'd be very unhappy !hat I do instead is have e4ternal network attached storage that can be network *$ounted* onto $y HIP (his could be an F e4port fro$ a :inu4 based P or an e4port fro$ a dedicated network back) up syste$ such as the !estern Eigital *My loud* devices (hese can be plugged into your :# without a dedicated P and e4pose a few gigabytes of shared storage (o deter$ine how $uch space is available, run the co$$and * df -k*$ df -k iles,stem ubi0rootfs de/tmpfs tmpfs tmpfs tmpfs tmpfs tmpfs

1N-blocks 8sed +/ailable 8se ou&ted o& 3666124 633344 30436G0 20  2!32#2 0 2!32#2 0 de/ 2!3!!2 0 2!3!!2 0 de/sm 2!3!!2 H6!H 24H6#H 3 ru& !120 4 !11H 1 ru&lock 2!3!!2 0 2!3!!2 0 s,sfscgroup !0612 4 !060G 1 ru&user1000

(he result shows the different file syste$s using the storage and how $uch is used and re$ains (he file syste$ of $ost interest to us is the one $ounted at *.* which is called *ubi0rootfs* If we look at this e4a$ple output, we see that its si%e is 3===1C 15 blocks (hinking in ter$s of 15 blocks isn't that useful and fortunately there are other flags For e4a$ple$ df -kB iles,stem ubi0rootfs Page $/

1-blocks 3HG#

8sed +/ailable 8se ou&ted o& 616 2#63 20 

de/tmpfs tmpfs tmpfs tmpfs tmpfs tmpfs

24G 24G 24G ! 24G !0

0 0 6 1 0 1

24G 24G 242 ! 24G !0

0 0 3 1 0 1

de/ de/sm ru& ru&lock s,sfscgroup ru&user1000

shows us the sa$e output but this ti$e in 1Mbyte blocks Fro$ this we /uickly see that the file syste$ hosts 3=A+ytes of which the operating syste$ and installed apps uses =1=M+ytes leaving us 
!hile resulting in a very rich and powerful interface, $y e4perience is that it takes too long to build the data for rendering

ee also•

$an819 L df 

•

+aobob

,etworking (he HIP hardware provides two distinct networking layers (hose are !iFi and +luetooth !iFi is used to create or 6oin a wireless (P.IP network while +luetooth is the co$$unication style used for personal device connections with a $ore li$ited range Page $

If we are in a graphical environ$ent, we can configure networking by running the co$$and *&m-co&&ectio&-editor* as root For e4a$ple$ sudo -E &m-co&&ectio&-editor

If we are at a te4t ter$inal shell, we can use * &mtui* !hen configuring a !iFi connection, we can specify that the configuration should be either auto$atic or $anual (he default is auto$atic which $eans that the !iFi access point supplies HIP with all the infor$ation it needs such as its IP address, gateway and E servers or$ally this is fine However if you are running HIP in a headless $ode, the chances are you $ay wish to give it a fi4ed IP address In that case, the configuration should be specified as $anual In a $anual configuration, you supply the para$eters 8local IP address, E server, gateway etc9 Here is an e4a$ple of a $anual configuration for $y environ$ent My choice was to have the HIP have a static IP address of 1<1@B110<-

Page $$

otice the E servers are BBBB and BBCC (hese are public E servers offered and $anaged by Aoogle 8thank you Aoogle>9 Nou are also likely going to want to change the host)na$e of your HIP (he default is *cip* but if you happen to have $ultiple instances of HIP, they will step on each other "unning *&mtui* allows us to change the value-

Pressing enter here allows us to choose a new na$e-

4perience see$s to show that although this does change the host)na$e of HIP, we also need to edit the etcosts file and change the na$e there

,etwork*anager  (he core of the networking subsyste$ in HIP is provided by the etworkManager dae$on (here are $any ways to interact with this co$ponent including-

• Page $)

&mcli L o$$and line tool

•

&mtui L (e4t based user interface

•

&m-applet L A7I task)bar tool

•

&m-co&&ectio&-ma&ager L A7I user interface

ee also•

!ikiPedia L etworkManager 

•

etworkManager ho$e page

•

$an L n$cli

,etworking tools ifconfig network command (his is a classic 7ni4 co$$and that is now clai$ed to be deprecated in favor of * ip*

ne of the pri$ary co$$ands is to list configured ip addresses For e4a$ple$ ip addr 1 lo ADDPB+:N8PAD'E(78PJ mtu H!!3H Udisc &oUueue state 8>N>D'> group default Ule& 1 li&kloopback 000000000000 brd 000000000000 i&et 126505051G scope ost lo /alid7lft fore/er preferred7lft fore/er i&etH 112G scope ost /alid7lft fore/er preferred7lft fore/er 2 %la&0 B(D+?:+)*8A*=:+)*8PAD'E(78PJ mtu 1!00 Udisc mU state 8P group default Ule& 1000 li&keter 0013efG03dbd brd ffffffffffff i&et 1#251HG51510324 brd 1#251HG5152!! scope global %la&0 /alid7lft fore/er preferred7lft fore/er i&etH feG06G4H21a0ecc2#!e6H4 scope li&k /alid7lft fore/er preferred7lft fore/er 3 %la&1 >D-:+((=E(B(D+?:+)*8A*=:+)*8PJ mtu 1!00 Udisc mU state ?D'> group default Ule& 1000 li&keter 003H6H21#6a3 brd ffffffffffff i&etH feG060e60ab40bcfH#aH4 scope li&k te&tati/e /alid7lft fore/er preferred7lft fore/er

ee also•

$an8B9 L ifconfig

ip network command (o say that the * ip* co$$and does a lot is a bit of an understate$ent It has a wealth of options

ee also•

$an8B9 L ip

•

ip co$$and cheat sheet

Page $,

iwconfig network command ee also•

$an8B9 L iwconfig

iwlist network command (he iwlist co$$and can be used to perfor$ a variety of infor$ation gathering tasks

(o scan available access points we can run$ i%list %la&0 sca&

ee also•

$an8B9 L iwlist

iwconfig network command (he iwconfig co$$and is used to report upon and $anage !iFi network interfaces It is installed as part of the *wireless)tools* package$ sudo apt-get i&stall i%co&fig

nce installed, we can list an interface's setup with$ i%co&fig %la&0 %la&0 =EEE G02511bg& E))=?"s%eetie" odea&aged reUue&c,25442 <;C +ccess Poi&t +42BG:G146#! *x-Po%er912 dBm (etr, sort limit6 (*) troff ragme&t troff E&cr,ptio& ke,off Po%er a&ageme&to& Ai&k Mualit,0 )ig&al le/el0 >oise le/el0 (x i&/alid &%id0 (x i&/alid cr,pt0 (x i&/alid frag0 *x excessi/e retries0 =&/alid misc0 issed beaco&0

ee also•

$an8B9 L iwconfig

nmcli (he n$cli is the etwork Manager o$$and :ine Interface It has a wealth of options o$e of the $ore interesting ones to us include-

•

&mcli de/ice %ifi list L Produce a listing of a scan of access points

ee also•

Page $<

$an L n$cli

wpa'cli

•

%pa7cli -i ifJ status L :ist the status of an interface For e4a$ple-

bssid9a42bGcG146#! freU92436 ssid9s%eetie id90 mode9statio& pair%ise7ciper9::P group7ciper9::P ke,7mgmt9'P+2-P)N %pa7state9:DPAE*E? address9003H6H21#6a3 uuid900b41cd!-#4ef-!ab0-G04a-fGbd3adf62af

(o connect to an access point fro$ the co$$and line run$ sudo %pa7cli add7&et%ork set7&et%ork &umJ ssid "))=?J" set7&et%ork &umJ ke,7mgmt >D>E e&able7&et%ork &umJ status

ee also•

$an8B9 L wpaTcli

wavemon network command (he wave$on co$$and provides a te4t.curses based screen representation of interaction of your !iFi chip-

Page $9

"emote login (o login fro$ one $achine to another we can use a variety of different techni/ues It is likely the case you want to login fro$ your P into your HIP, however the reverse is also possible depending on what is running on your P !e will assu$e for 6ust now that the goal is to get fro$ the P to HIP ne of the $ost co$$on re$ote login tools is called ss !e can use the co$$and$ ss useridJVostJ

to open a new session to the re$ote host and login with the supplied userid #t this point, we will be pro$pted for the password of the userid It is co$$on in our develop$ent environ$ent that we will be doing lots of re$ote ssh co$$ands and we want our local P userid to be a trusted partner to the re$ote If our P is running a :inu4 flavor, the following recipe can be followed to set up trust between the two In our story we will assu$e that the P has a hostna$e of * ost-pc* and that HIP has the hostna$e of * ost-cip* !e will also assu$e that the userid on the P is * pcuser* while on HIP it will be * cip* n the P, in the user's ho$e directory, run$ ss-ke,ge& -t rsa

!hen pro$pted for a pass phrase, si$ply hit enter and not provide one n HIP, login as *cip* and $ake a directory in the ho$e directory called * 5ss* +ack on the P, in the user's ho$e directory, we want to copy the public key into the newly created directory on HIP appending to a new file called * autoriCed7ke,s* !e can do this with$ cat 5ssid7rsa5pub | ss cipVost-cip Wcat JJ 5ssautoriCed7ke,sW

Following this, if we now run $ ss cipVost-cip

on the P, we will i$$ediately be logged into HIP without a password challenge (here are alternative co$$ands for re$ote login such as tel&et and rlogi& but ss is considered the current best practice

-omain ,ame %er'ice (he internet 8or other (P.IP network9 uses IP addresses to identify $achines #n internet address is a 3 bit address co$$only written as C deci$al bytes of data separated by periods& eg 13C ote that this is known as an IPvC address and there are now also IPv@ addresses which are 1B bit addresses (rying to refer to a $achine by its IP address would be a big challenge to say the least (o solve that proble$, a resolution $echanis$ was created which $aps na$es to IP addresses (his is called the Eo$ain a$e ervice 8E9 !hen we know the na$e of a $achine, we can supply its na$e and E will return the IP address corresponding to that na$e nce the software knows the IP address, it can then Page )0

co$$unicate with the target directly #s you can i$agine the database of IP addresses to na$es could be incredibly large & and it is In fact it is what is known as a distributed database $eaning that the $apping is itself partitioned down into lower and lower levels o instead of one $assive database, there are s$aller and s$aller databases that have ad$inistrative control over subsections If we were to think of it in a hierarchical fashion, we have databases for each of the *top level do$ains* (hese are-

•

co$

•

org

•

net

•

gov

•

etc etc etc

For each entry in those databases, they then point to $achines which $ay then host further databases & for e4a$ple * google5com* would look up the database entry at *co$* for the entry for *google* If we further ask for *pla,5google5com*, this would then look up the entry for *google5com* which would then ask a E server there for the address of the $achine called *pla,* (hankfully, we don't have concern ourselves with these levels of details when actually resolving host na$es to IP addresses when using HIP Instead, we tell HIP about a single E server that is part of the hierarchy and we send it re/uests It in turn knows the locations of top level do$ain servers and the re/uests get forwarded up the chain until we achieve resolution (here are other opti$i%ations at play including caching which $ake this $ore than acceptably fast (he /uestion though & is how does HIP find the address of the original E server that it should use to begin with (he answer to this depends on how HIP connects to your network If you are using EHP, then when the network starts your HIP will contact the EHP server on your own network and will be boot) strapped with all the infor$ation it needs fro$ the EHP server (his obviously $oves the proble$ further to the right & but the chances are high that your EHP server is built into your $ode$ supplied by your internet service provider 8IP9 such as your cable or E: provider !hen they supplied the $ode$, they configured the up)strea$ services and your $ode$ *by $agic* gets the infor$ation it needs However & there is also the concept of your :# #ddresses in the range 1<1@B14 are defined to be local addresses (his $eans that the network traffic on that :# lives only locally and doesn't propagate into the Internet For e4a$ple, in $y house, $y HIP $ight have the IP address 1<1@B1 while in your house, your HIP $ight have e4actly the sa$e address (his $eans that you can connect to other devices in your own house that have IP addresses in the range 1<1@B11 to 1<1@B12C with i$punity while I can do the sa$e and none of us will tread on each other (his too is great & but what now if I don't want to re$e$ber that 1<1@B1 is $y HIP while 1<1@B13 is !indows P while 1<1@B1C is a :inu4 bo4 !hat we want is the ability to resolve host na$es 6ust as we do with E For e4a$ple, I $ight want to ping * m,cip* or *m,%i&do%s* or *m,li&ux* by na$e rather than re$e$ber the addresses (his is where the syste$ file called etcosts co$es into play (his is a te4t file which we Page )1

can edit !ithin the file we can add lines of the for$=P +ddressJ ost&ameJ

for e4a$ple1#251HG5152 m,cip 1#251HG5153 m,%i&do%s 1#251HG5154 m,li&ux

nce added to the file, any atte$pt to resolve these host na$es would succeed !hat happens is that the na$e resolution subsyste$ of HIP  first looks for a $atch of host na$e in etcosts and, if not resolved there, then $akes contact with a E server for Internet resolution If we know the host na$e of a $achine and want to see its IP address, we use the co$$and$ ost ost&ameJ

for e4a$ple$ ost %%%5google5com %%%5google5com as address 21H5!G521654 %%%5google5com as =P/H address 2H06fGb0400fG022004

ote that the order of resolution for a host na$e is governed by the content of the file called etc&ss%itc5co&f

-,% %er'ice -isco'ery and *ulticast -,% (he Eo$ain a$e ervice can be thought of as a logical distributed database in which entries $ap hostna$es to IP addresses (his allows one to find a host's IP address by its na$e However, if we think this through, it relies on static IP addresses and ad$inistrators to register the corresponding hostna$es (he concept of $ulticast E is that if you are on a broadcastable :# seg$ent then if you want to reach a host, you can broadcast *Hey  what is the IP address of the host called JNG* (he principle being that if a host witht hat na$e is on the :# then it can respond back with its own IP address (he result of this is a dyna$ic $apping of logical host na$es to current IP addresses without any ad$inistrator $anual intervention If you see the acrony$ *$dns* that is *$ulti cast Eo$ain a$e ervice* ne such i$ple$entation of Multicast E on :inu4 is called #vahi #vahi runs as the s,stemd dae$on called *a/ai-daemo&* !e can deter$ine whether or not it is running with$ s,stemctl status a/ai-daemo& X a/ai-daemo&5ser/ice - +/ai m?>)?>)-)? )tack Aoaded loaded .libs,stemds,stema/ai-daemo&5ser/iceY e&abled +cti/e acti/e .ru&&i&g si&ce 'ed 201H-01-20 22133! :)*Y 1 da, 13 ago  ai& P=? 3G4 .a/ai-daemo& )tatus "a/ai-daemo& 05H531 starti&g up5" :
Page )2

(he avahi)dae$on utili%es a configuration file found at etca/aia/ai-daemo&5co&f (he default na$e that avahi adverti%es itself as is the local hostna$e !hen host)na$e resolution is perfor$ed, the syste$ file called etc&ss%itc5co&f is used to deter$ine the order of resolution pecifically the hosts entry contains the na$e resolution #n e4a$ple would beosts

files md&s47mi&imal S>D*D8>?9retur&T d&s

!hich says *first look in etcosts, then consult $E and then use full E* !hat this $eans is that a device which adverti%es itself with $E can be found via a lookup of *ost&ameJ5local* For e4a$ple, if I boot up HIP which gets a dyna$ic IP address through EHP and the hostna$e of that $achine is * cip1*, then I can reach it with a do$ain na$e address of *chip1 5local* If the IP address of the device changes, subse/uent resolutions of the do$ain na$e will continue to correctly resolve  #vahi tools are not installed by default but can be installed using the *a/ai-utils* package$ sudo apt-get i&stall a/ai-utils

(o see the list of $E devices in your network, we can use the a/ai-bro%se co$$and For e4a$plea/ai-bro%se -at ] %la&1 =P/H cip1 Sce6#cf21db#!T ] %la&1 =P/4 cip1 Sce6#cf21db#!T ] %la&0 =P/H piCero S003H6H21#6a3T ] %la&0 =P/H raspi3 SbG26eb#dfcH0T ] %la&0 =P/H cip1 Scc6#cf21db#!T ] %la&0 =P/4 piCero S003H6H21#6a3T ] %la&0 =P/4 raspi3 SbG26eb#dfcH0T ] %la&0 =P/4 cip1 Scc6#cf21db#!T ] %la&0 =P/H piCero ] %la&0 =P/H raspi3 ] %la&0 =P/4 raspi3 ] %la&0 =P/4 piCero ] %la&0 =P/4 '?,:loud ] %la&0 =P/4 '?,:loud ] %la&0 =P/4 '?,:loud ] %la&0 =P/4 Ai/i&g (oom ] %la&0 =P/4 1234!H6G#

'orkstatio& local 'orkstatio& local 'orkstatio& local 'orkstatio& local 'orkstatio& local 'orkstatio& local 'orkstatio& local 'orkstatio& local (emote ?isk a&ageme&t local (emote ?isk a&ageme&t local (emote ?isk a&ageme&t local (emote ?isk a&ageme&t local +pple ile )ari&g local 7%d-2go57tcp local 'eb )ite local 7googlecast57tcp local 7team/ie%er57tcp local

(o access an $E adverti%ed server fro$ Microsoft !indows, you will need a service si$ilar to #pple's +on6our installed +on6our is distributed as part of #pple's i(unes product nce installed, we should be able to access the published servers at their &ameJ5local address # partner windows tool called *+on6our +rowser* is available which displays an $E listing of servers on windows ee also•

avahi ho$e page

•

$an819 L avahi)browse

•

$an829 L avahi)dae$onconf 

Page )/

•

+on6our +rowser 

•

Gero onfiguration etworking 8Geroconf9

(ccessing your )*+P from the +nternet If you want to be able to access your HIP fro$ the Internet, there are so$e pu%%les that need solved !hen we think about how a HIP is connected, it is usually via !iFi to your local ho$e network (his $eans that it will have an IP address that is local to your environ$ent (ypically it will be 1#251HG515x (hese local addresses are, by definition, not global and hence you can't access HIP fro$ the Internet (o solve that proble$ we $ust use a service such as the free Euck E server (he way this works is that we run an application on HIP 8or on another P on your network9 which $akes a connection to Euck E passing in your authori%ation key ince the connection to the Euck E server now i$plicitly knows the IP address of your router and e4plicitly knows the authori%ation key, it can $ap those together to provide a E resolution

For e4a$ple, if you visit wwwduckdnsorg and register for an authori%ation key, you will get the opportunity to re/uest a sub)do$ain address For e4a$ple *&eilkolba&* (his will $ean that in future, a re/uest to the host)na$e of * &eilkolba&5duckd&s5org* will resolve to the current  IP address of your router If you now configure your router to pass (P.IP port specific traffic to HIP, we will have achieved the desired task

%haring .indows files It is likely we will want to access and share files between HIP and either a !indows or :inu4 desktop (his $eans that we will want to e4pose file syste$s fro$ HIP and access the$ on the re$ote $achines # protocol called the o$$on Internet File yste$ or IF will be our friend (his is the protocol adopted by Microsoft for !indows file and printer interoperability Fro$ a historical perspective, a precursor to IF was called erver Message +lock or M+ It is fro$ M+ that we get the na$e %a*Ba (hings offered by a IF server are called *shares* # IF server has a na$e and is used to /ualify the identity of the specific share we want to access (he way to address a share is with a sche$e called the 7niversal a$ing onvention or 7 (his is of the for$ ^^:=)7)er/erJ^)are &ameJ For e4a$ple, if we wish to access a directory called *$ydir* offered by a IF server called MN"D", we could run the following windows co$$ands:J &et use C ^^L)E(E(^m,dir

!ithin HIP , we will see a nu$ber of de$on progra$s that collaborate together to provide the a$ba services (hese include-

•

smbd L (he de$on that $akes the data available fro$ the IF server and provides security control

Page )

•

&mbd L I$ple$ents the et+I a$e erver or + which is also called !I fro$ a !indows perspective

n the windows side, we have so$e useful networking co$$ands including-

•

ipconfig

•

net

•

nbtstat L :ist et+I over (P infor$ation

:et us assu$e that we wish to share files fro$ HIP so that they are accessible fro$ a !indows $achine (o start we need to add a package to our HIP environ$ent (his is called samba $ sudo apt-get i&stall samba

 #fter the sa$ba package is installed, we want to set a sa$ba password for our sharing user using the co$$and *smbpass%d*$ sudo smbpass%d -a cip

!e will be pro$pted twice for the password ow we need to define which directories will be e4ported (o do this we need to edit the a$ba configuration file found at etcsambasmb5co&f #t the end of the file add an entry for each directory to be e4ported In this e4a$ple, we e4port a directory on the HIP called *omecip+rdui&o* which will appear as the share called * +rdui&o* S+rdui&oT comme&t9*esti&g o&l, please pat9omecip+rdui&o /alid users9cip read o&l,9&o

Having $ade the configuration changes, we stop and restart the a$ba de$ons using$ sudo s,stemctl stop smbd $ sudo s,stemctl start smbd

If we now open a windows e4plorer and enter the IP address of our HIP 8in the following e4a$ple $y HIP is at 1#251HG5151039-

Page )$

!e see the e4posed shares If we try and open it, we will be pro$pted for a userid and password-

and once entered, we should have access to the file syste$ If we want to run so$e HIP  side tests, we can install the * smbclie&t* package using$ sudo apt-get i&stall smbclie&t

e4t we can run the following co$$and to e4a$ine what is available$ smbclie&t -A localost ->

(he logs for sa$ba can be found atPage ))

/arlogsamba

 #n obvious ne4t /uestion after having seen how to e4pose a HIP file syste$ to !indows is can HIP access a !indows file syste$ n $ost :inu4 variants 8including "aspberry Pi9 the answer is a solid yes adly, at the ti$e of writing, the answer is no for HIP In order to work with !indows file syste$s, a kernel $odule called *cifs* needs to be present and in the current builds of HIP, it si$ply is not there ee also•

How to reate a etwork hare Dia a$ba Dia :I 8o$$and)line interface.:inu4 (er$inal9 ) 7nco$plicated, i$ple and +rief !ay>

Creating an access point !e know that HIP has a built in !iFi adapter, but did you know it has two (here is a second !iFi interface called %la&1 8the pri$ary is called %la&09 !hy have two & well & what about have the HIP appear as an access point or$ally when we think of a !iFi device we think of it as connecting to our hub at ho$e that is connected to the Internet via E: or cable or so$e other broadband $echanis$ !hat is really happening here is that the !iFi device you are connecting fro$ is acting as a !iFi tation and the hub is acting as a co$ponent called a !iFi #ccess Point If we configure HIP to be an access point then what we achieve is the ability for other !iFi stations 8eg other HIPs, "aspberry Pis, your cell phone, other co$puters etc &9 to connect to HIP !e start by installing d&smasU (his is the application that provides EHP and E support EHP is used to allocate IP addresses when a new !iFi station connects E is the co$ponent used to resolve hostna$es to IP addresses !e install by running$ sudo apt-get i&stall d&smasU

 #fter installation, we need to perfor$ a configuration change !e need to instruct d&smasU that it should only  handle the wlan1 interface and leave %la&0 alone In addition, we want to supply the range of IP addresses that $ay be supplied !e create a new file called *access7poi&t5co&f* in the etcd&smasU5d directory$ sudo &a&o etcd&smasU5daccess7poi&t5co&f

!ithin this file, add the following two linesi&terface9%la&1 dcp-ra&ge91625205051001625205052!01d

e4t we want to define wlan1 as an interface and give it a static IP address !e edit the file etc&et%orki&terfaces$ sudo &a&o etc&et%orki&terfaces

 #t the end of the file, we addauto %la&1 Page ),

iface %la&1 i&et static address 1625205051 &etmask 2!!52!!52!!50

ow we can start the wlan1 interface with$ sudo ifup %la&1

!hat re$ains is to configure the hostapd progra$ (his is the dae$on which handles connection re/uests fro$ !iFi stations !e need to configure it with a nu$ber of para$eters !e create a file called etcostapd5co&f using$ sudo &a&o etcostapd5co&f

and add the following linesi&terface9%la&1 dri/er9&lG0211 ssid9cip7ap ca&&el91 ctrl7i&terface9/arru&ostapd

f the above lines, you are likely going to be want to be custo$i%ed for your own environ$ent (he line which starts *ssid9* (his is where you supply the IE 8network9 na$e of your !iFi environ$ent (his is what !iFi stations 8end users9 will see as an available !iFi access point (his configuration file has to be associated with hostapd !e edit the file called etcdefaultostapd$ sudo &a&o etcdefaultostapd

!ithin the file we find the line that references ?+ED>7:D> and change its value to point to our configuration file !e will change the line to read?+ED>7:D>9"etcostapd5co&f"

 #ll that re$ains is to restart the hostapd service with$ sudo s,stemctl restart ostapd5ser/ice

ow if we browse the !iFi network, we will find a new access point called * cip7ap*

Page )<

Nou will notice that we can connect to it without providing any credentials (hat isn't a great situation as it allows anyone to connect to your HIP !hat we will do ne4t is add a passkey that the !iFi station needs to present for authentication (o do this we edit the etcostapd5co&f file and add the following lines%pa92 %pa7ke,7mgmt9'P+-P)N %pa7passprase9pass%ord

(o restart hostapd to see the changes, run again$ sudo s,stemctl restart ostapd5ser/ice

(he *%pa7passprase9* line contains the password you want users to enter to be able to connect It is i$portant to reali%e that the current HIP kernels do not support network address translation 8nat9 !hat this unfortunately $eans is that you can not route traffic receive through the wlan1 interface out through the wlan0 interface (he i$plication of this is that you can't use HIP as either a !iFi router, bridge or e4tender ee also•

How to create a very basic !iFi access point on HIP

•

!ikipedia L hostapd

•

Hostapd ho$e page

•

hostapd configuration file

•

dns$as/

•

$an8B9 L dns$as/

,etwork &ile %ystem /,&%0 (he 7ni4 file syste$s provide a hierarchical file syste$ $odel (hink of this like a real)world tree # tree has a trunk and a trunk has branches Fro$ those branches sprout $ore Page )9

branches and the story continues In :inu4, we have a directory called *.* also known as the root of the file syste$ +eneath this we have $ore and $ore directories In early 7ni4, each physical disk could be for$atted with the :inu4 file syste$ and *grafted* onto the hierarchical structure For e4a$ple, if I created a physical disk that I wanted to use as the storage area for all $y user's data, I could graft this disk onto the *.ho$e* directory of the file syste$ !hen a user transition as follows$ cd  $ cd ome

(hen the transition into *ho$e* resulted in access to the storage of the disk drive (he act of grafting disk storage onto the :inu4 file syste$ is called *$ounting* and we can now say that we have *$ounted the .ho$e file syste$* and that *.ho$e* represents a $ount point where we transition fro$ one file syste$ to another (his $echanis$ allows us to e4tend the :inu4 file syste$ with $ore storage as needed !ith the arrival of fast networking, an additional concept was brought to light !hat if we could graft onto our local file syste$ a *reference* to a file syste$ owned by a re$ote $achine # transition through the $ount point where the re$ote file syste$ is attached would then cause network re/uests to read and write data fro$ the re$ote $achine (his idea has been i$ple$ented in 7ni4 syste$s through the etwork File yste$ 8F9 (he etwork File yste$ 8F9 allows us to $ount directories hosted by one :inu4 $achine on the file syste$ of another For e4a$ple, i$agine the HIP e4posed a local file syste$ and our develop$ent :inu4 syste$ $ounted that e4posed file syste$ !e could then edit and co$pile files on our P desktop and the files would i$$ediately be present on the HIP (o setup F on a :inu4 $achine, we need the following packages installed-

•

nfs)co$$on

•

nfs)server 

•

port$ap

sudo apt-get i&stall &fs-commo&

Mount a re$ote file syste$ $ mou&t -t &fs =P addressJremote director,J local director,

(o see what has been e4ported fro$ a re$ote F server, run$ sudo so%mou&t -e ostJ

to see what has been e4ported fro$ our local F server run$ sudo so%mou&t -e

(o configure an F server1 Make sure that the directory you wish to share e4ists  #dd it to etcexports & for e4a$ple omecip R.r%s,&c Page ,0

3 "eload the F configuration by running $ sudo exportfs -r

C Dalidate that the file syste$s are not e4ported by running $ so%mou&t -e

2 !e $ay have to enable rpcbi&d with$ sudo update-rc5d rpcbi&d e&able $ sudo rpcbi&d start

(o un)$ount an F $ounted file syste$, we can use the u&mou&t co$$and If we try and access an F $ounted file syste$ and the network is not present or down, we will block the caller If we want to force an un)$ount an F file syste$ while the network is down, we $ust use the u&mou&t -l co$$and which perfor$s a la%y un)$ount

%ockets PI programming ince your HIP has network accesss, you can write  language applications to send and receive data (he classic 7ni4 level #PI for (P.IP progra$$ing is called *sockets* #t a high level, one $akes a call to socket. which returns a handle to an endpoint of co$$unication Fro$ here, the progra$ will decide whether it is going to be a socket client 8a progra$ that calls outbound to initiate work9 or a server 8a progra$ that passively listens for inco$ing connections fro$ other clients9 (o be a client, the ne4t #PI that is usually invoked is co&&ect. (his provides the IP address and port nu$ber to which the client wishes to connect nce that succeeds, the client can then send and receive arbitrary a$ounts of data through the socket using se&d. and rec/. !hen done, it can call close. to ter$inate the connection hould the application wish to be a server, it will associate itself with a port on the local $achine using the bi&d. call and then e4ecute a liste&. call to begin listening for inco$ing client re/uests Finally, it will e4ecute an accept. call which causes the server to block and wait for new inco$ing client re/uests !hen a client does connect, the accept. call will unblock and return a new socket that represents the connection to the client "eturn codes fro$ the sockets #PIs are usually integers If the value )1 is returned, this indicates an error and the global err&o is further set to indicate the nature of the error ee also•

(P.IP ockets in - Practical guide for progra$$ers

Finding an +P address from a hostname I$agine we are given the hostna$e of a server and we wish to connect with it !hen we look at the sockets #PI, we will find that they e4pect 3bit IP addresses !hat we need is a Page ,1

$echanis$ to convert a hostna$e into its corresponding IP address Fortunately there is a function that will do 6ust that for us It is called * getostb,&ame* It and its related data structures are defined in the header called * &etdb5* (o use, we invoke getostb,&ame. passing in a string representation of the hostna$e or a string representation of the IPvC dotted deci$al address !hat we get back is a pointer to a struct oste&t (his structure has been populated by the getostb,&ame. call and we can e4a$ine its content to obtain the results pecifically, to find the IP address we can useoste&t57addr

(he return type of this is a * car R* which will point to the IP address For e4a$plestruct oste&t Rm,;ost 9 getostb,&ame."%%%5kolba&5com"Y car Rip+ddress 9 m,;ost-J7addrY

If we can't resolve the hostna$e or so$e other error has occurred, the return fro$ getostb,&ame. is 7:: (he addresses returned are already in network byte order so no conversion fro$ host byte order is needed nor should be perfor$ed Having 6ust e4plained getostb,&ame. we are now going to say that it has been $ostly superseded by the getaddri&fo. call ee also•

$an839 L gethostbyna$e

)reating a socket client :et us now look at so$e practical e4a$ples First we will set up the creation of a socket client connection (his will allow us to connect fro$ a  progra$ using sockets to an already e4isting ocket server running else where In order to for$ a connection we will assu$e that we know the hostna$e or IP address of the target server as well as the port nu$ber on which it is listening (he first thing we will do is create a socketi&t rcY  (etur& code for cecki&g i&t s 9 socket.P7=>E* )D:N7)*(E+ =PP(D*D7*:PY struct sockaddr7i& ser/er+ddrY ser/er+ddr5si&7famil, 9 +7=>E*Y ser/er+ddr5si&7addr5s7addr 9 _Y ser/er+ddr5si&7port 9 to&s.portY rc 9 co&&ect.s .struct sockaddr Rser/er+ddr siCeof.ser/er+ddrY  'e are &o% co&&ected to te target

)reating a socket server (he socket server begins with the creation of a socket in e4actly the sa$e $anner as a client However, once the socket is created we bind it to local IP port and then ask it to start listening

Page ,2

for inco$ing connections re/uests fro$ clients ince the server doesn't know when a client will connect, it e4ecutes an accept. call which nor$ally blocks waiting for a client connection to arrive !hen a client does connect, accept. returns with a new socket connection that is ready to be used and constitutes the connection to the client i&t s 9 socket.P7=>* )D:N7)*(E+ =PP(D*D7*:PY struct sockaddr7i& ser/er+ddressY ser/er+ddress5si&7famil, 9 +7=>E*Y ser/er+ddress5si&7addr5s7addr 9 to&l.=>+??(7+>LY ser/er+ddress5si&7port 9 to&s.portY rc 9 bi&d.s .struct sockaddr Rser/er+ddress siCeof.ser/er+ddressY liste&.s !Y struct sockaddr7i& clie&t+ddressY i&t le> 9 siCeof.clie&t+ddressY i&t clie&t)ocket 9 accept.s .struct sockaddr Rclie&t+ddress le>Y

If we don't care about the address infor$ation of the client then the address structure and length para$eters can be supplied as >8AA ee also•

$an89 L accept

•

$an89 L bind

•

$an89 L listen

ending data through a socket (he #PI to send data through a socket is called se&d. It takes as para$eters the socket descriptor to use, a pointer to the raw $e$ory to send, the length of the data to send and so$e optional flags rc 9 se&d.s buffer siCe 0Y

ee also•

$an89 L send

eceiving data through a socket (he #PI to receive data through a socket is called rec/. !hen called, it e4pects the socket descriptor through which to receive the new data It also takes a buffer point into which the data received will be placed (he si%e of the buffer is also supplied :astly there will be so$e optional flags (he return fro$ this function is the si%e of the data actually received which could be less than the buffer si%e supplied which is the $a4i$u$ a$ount of data that can be received in one re/uest (he call can block if there is no data available It can block the caller until such ti$e as there is data (he blocking can be over)ridden to provide alternate options #n error is indicated by the return value of )1

ee also-

Page ,/

•

$an89 L recv

)losing a socket !hen either the server side or the client side of the socket connection wishes to indicate that it has finished, it should close the socket with a call to close.

ee also•

$an89 L close

.DP programming !here (P socket progra$$ing is strea$ based and data pushed in one side appears on the partner side, 7EP socket progra$$ing works on the concept of datagra$s # datagra$ is a packet of data that is trans$itted fro$ one end to another as a unit (he $a4i$u$ si%e of a datagra$ is @C5 7nlike (P, there is no assured delivery !hat this $eans is that if a sender sends a datagra$ it is possible for the datagra$ to never reach the intended recipient and neither end will know it was lost 7EP is a fire and forget protocol !ith these apparent li$itations, what then is the value of 7EP (he first is that because it is datagra$ oriented, it has a s$aller overhead in ter$s of trans$ission (here is no receipt of delivery and hence no e4tra chatter ince a datagra$ is delivered as a unit, it also $eans that there is a logical record boundary which is not present in (P However the $ost co$pelling reason for 7EP is that there needs to be no pre)ac/uired connection between a sender and a receiver (his $eans that a sender can send a datagra$ to a recipient without first having to for$ a connection # significant value for this is that a sender can broadcast a datagra$ to a set of endpoints and all the recipients will receive a copy ontrast this with (P where if I want to send data to a set of $achines, I have to send a distinct copy of that data to each partner

!e use 7EP by creating a socket but flag it as a datagra$i&t s 9 socket.+7=>E* )D:N7?<(+ 0Y

e4t, on the server, we bind the socket to a local port to act as the endpoint using the bi&d.  #PI Finally, on the server, we can block waiting for an inco$ing datagra$ using the rec/from.  #PI n the client, we perfor$ a socket. call to create a socket and then e4ecute a se&dto.  #PI call to send a datagra$ to the target server ee also•

$an89 L sendto

•

$an89 L recvfro$

Page ,

1a'a%cript socket2io  # package for ?avacript called *socket5io* provides a wealth of network progra$$ing capabilities (o install, we can use np$$ &pm i&stall socket5io

ee also•

np$ L socketio

%ending an email (here $ay be ti$es where you wish to send an e$ail fro$ your HIP Hopefully it isn't because a sensor had detected that your house is on fire 8although you $ay actually want that9 Maybe you want to receive an e$ail when ?ohnny co$es ho$e fro$ school In this case you could build a $otion sensor outside the door that, when triggered, takes a photo of the scene and sends it to your ca$era (he way $ail works on a :inu4 syste$ is that a shell progra$ called $ail co$$unicates with a local progra$ called se&dmail (he $ail is handed off to se&dmail and then se&dmail relays it onwards out onto the Internet (he se&dmail application also handles inco$ing e$ails and it can beco$e /uite co$ple4 If all we want to do is send e$ails fro$ HIP, there is an easier solution through the package called ssmtp First we want to install ssmtp using$ sudo apt-get i&stall ssmtp

Here is a sa$ple configuration file for a AoEaddy hosted e$ail accountF F :o&fig file for s)*P se&dmail F F *e perso& %o gets all mail for userids  1000 F ake tis empt, to disable re%riti&g5 root9cipVkolba&5com F *e place %ere te mail goes5 *e actual maci&e &ame is reUuired &o F @ records are co&sulted5 :ommo&l, mailosts are &amed mail5domai&5com mailub9smtpout5secureser/er5&et +ut8ser9cipVkolba&5com +utPass9RRRRRRRRR 8se*A)9>D 8se)*+(**A)9>D F 'ere %ill te mail seem to come from` re%rite?omai&9kolba&5com F *e full ost&ame ost&ame9smtpout5secureser/er5&et F +re users allo%ed to set teir o%& rom address` F LE) - +llo% te user to specif, teir o%& rom address F >D - 8se te s,stem ge&erated rom address Page ,$

romAi&eD/erride9LE)

 #fter installation we are ready to send e$ails, however the $ail sending tools are also not yet installed (o install those, we need to install the package called mailutils$ sudo apt-get i&stall mailutils

nce installed we have the classic mail co$$and (o send an e$ail fro$ the co$$and line we can use$ eco ";ere is ,our mail" | mail -s "Lour ail" -+ etcpass%d cipVkolba&5com

!ith this in place, we can now send an e$ail fro$ al$ost any app For e4a$ple, when a sensor attached to the Pi detects so$ething un)toward, we can send an e$ail to alert so$eone ne of the things to consider about e$ails is that they are *people interrupters* !hen an e$ail arrives we usually want to attend to it "eceiving irrelevant e$ails or e$ails that don't tell us anything we didn't already know can be a strong negative #s such, be very cautious when writing applications that send e$ails #t a $ini$u$, think through the fre/uency with which e$ails are sent If you have a sensor which, when it triggers can trigger again repeatedly, design your solution so that only one e$ail is sent and not hundreds of e$ails that will $erely clutter 8and annoy9 the recipient

*3TT (he MU (ele$etry (ransport 8MU((9 is a protocol for publish and subscribe style $essaging It was originally invented by I+M as part of the MUeries fa$ily of products but since has beco$e an industry standard governed by the asis standards group (he latest specification version is 311 +eing Pub.ub, this $eans that there is a broker 8an MU(( +roker9 to which subscribers can register their subscriptions and publishers can sub$it their publications Publications and subscriptions agree on the topics to be used to link the $essages together # client can be a publisher, a subscriber or both (he value of MU(( is that it can be used to deliver data fro$ an application running on one $achine to an application running on another I$$ediately we see$ to see an overlap between MU(( and "( calls but there are so$e $a6or differences In a "( environ$ent, when you for$ a connection fro$ a client to a server, the server $ust be available in order for the client to deliver the data !ith MU(( that is not necessarily the case (he client can publish a $essage which can then be held by the broker until such ti$e as the receiving application co$es on)line to retrieve it (his is a store and forward $echanis$ very $essage $ust have a topic associated with it (opics are broken into topic levels (here are wild)cards

• Page ,)

] L ingle topic level wild)card

eg a]c would subscribe to abc and axc

•

V L Multi topic level wild)card

eg aF would subscribe to aa&,ti&gJ MU(( is built on top of (P.IP lients connect to the broker 8not to each other9 over a (P connection (here is a /uality of service re/uested by a client (his is encoded in the Uo field-

•

Mo)90 L end at $ost once (his can lose $essages #t $ost once $eans perhaps never

•

Mo)91 L end at least once (his $eans that the $essage will be delivered aying this another way, a $essage will not be discarded or lost However, duplicates can arrive & ie the $essage can be delivered twice or $ore

•

Mo)92 L end e4actly once (his $eans that the $essage will not be lost and will be delivered once and once only

MU(( also has the capability to buffer $essages for subse/uent delivery For e4a$ple, if a client subscriber is not currently connected, a $essage can be /ueued or stored for delivery to the client when it eventually re)connects !e call a client that is not connected an off)line client For a subscription, we have the choice to deliver all the /ueued $essages for a client or 6ust the last $essage (o understand the difference, we can i$agine a published $essage that says *I will be attending the party* & we want all such $essages sent to the client because they are all of interest However if we think of a published $essage of *(oday's forecast is sunny and war$* then there $ay be no need for old $essages and only the current weather forecast is of interest to us (he last $essage published on a topic is called the *retained $essage* !hen a client subscribes, it can ask to receive the last $essage i$$ediately & so even if a subscription takes place after a previous publication, it can still receive data i$$ediately lients $ake their status known to the broker so the broker can tell if a client is connected (his is achieved via a keep)alive.heartbeat If a client connection is lost because of a network disconnection, the broker can detect that occurrence (his is where we get $orbid !e define this as the client having *died* In the real world, when so$eone dies, there $ay be a last *will and testa$ent* which are the desired of what the person wanted to happen when they die MU(( has a si$ilar concept # client can register a $essage to be published in the event of the clients death (his is re$e$bered by the broker and in the event of the client dieing, the broker will perfor$ the role of the attorney and publish the last registered *will and testa$ent* $essage on behalf of the deceased client ee also-

Page ,,

MU(( Hive Mos/uitto •

MU((org

•

asis MU(( spec L 311

•

Mos/uitto,org

•

Nou(ube- Internet of (hings L !hy Nou eed MU((

•

#I Message Uueuing (ele$etry (ransport 8MU((9

•

#I MU(( D311 pecification

#/&& Protocol Protocol

lient sends onnect +roker replies with onnack onnect MU(( packet

•

clientId L (he identity that the client clai$s to be 

•

cleanession

•

userna$e

•

password

•

last!ill(opic

•

last!illUos

•

last!illMessage

•

keep#live

onnack

•

sessionPresent

•

returnode

Publish

•

packetId

•

topica$e

•

/os

•

retainFlag

•

payload

•

dupFlag

Page ,<

Puback  Pubrec

•

packetId

Pubrel

•

packetId

Pubco$p

•

packetId

ubscribe

•

packetId

•

/os

•

topic1

•

/os

•

topic

•



uback Eisconnect

#os0uitto #/&& ne of the $ost prevalent i$ple$entations of MU(( is called osUuitto and is available as an open source i$ple$entation n a :inu4 syste$ we would install with$ sudo apt-get i&stall mosUuitto

7nfortunately, the version of Mos/uitto supplied by the repository is 13C which is /uite old and pre)dates $any i$portant functions such as websocket support (o resolve this, you $ay have to download the latest version and build yourself !here s,stemd is installed, mosUuitto is controlled by it (o see if it is running e4ecute $ s,stemctl status mosUuitto X mosUuitto5ser/ice - A)B mosUuitto M** /351 message broker Aoaded loaded .etci&it5dmosUuitto +cti/e acti/e .ru&&i&g si&ce ri 201H-0G-0! 234416 :?*Y 1mi& 1s ago :
(he default configuration file for mosUuitto is etcmosUuittomosUuitto5co&f Messages fro$ mosUuitto are logged to /arlogmosUuittomosUuitto5log (wo sa$ple applications are provided that perfor$ subscriptions and publications (hese are

Page ,9

mosUuitto7sub and mosUuitto7pub (hese are distributed as part of the mosUuittoclie&ts package  #s a si$ple test, open two ter$inal sessions In one run$ mosUuitto7sub -t greeti&g

In the other run$ mosUuitto7pub -t greeti&g -m ";ello 'orld"

Nou will see the published $essage appear in the subscriber window :et us now dig a little further into a mosUuitto configuration file !ithin there, we can specify $ultiple *liste&er* entries (hese can bind to a port or a port and interface !ithin a listener section, we can configure the protocol that the listener should use +y default, it will be plain (P for nor$al client connections but we can specify that the protocol should be *%ebsockets* For e4a$ple, adding the following into the mosUuitto5co&f fileliste&er G0G1 protocol %ebsockets

will cause mosUuitto to listen for websocket clients on port G0G1 If you want to listen on both standard $/tt protocol and websocket, then you will need $ultiple listener definitions liste&er 1GG3 protocol mUtt liste&er G0G1 protocol %ebsockets

ee also•

Mo/suittoorg

•

$an819 L $os/uittoTsub

•

$an819 L $os/uittoTpub

•

$an829 L $os/uittoconf 

•

MU(( o$$unity !iki

Building mosquitto from source

+ecause the current distribution of mosUuitto is /uite old, we $ay want to download, build and install mosUuitto fro$ source (o obtain the source, visithttp-..$os/uittoorg.download. Eownload the AGip file and e4tract #t the ti$e of writing this was $os/uitto)1C=targ% In the resulting directory, we will find a akefile which can be run with make I reco$$end editing co&fig5mk and changing'=*;788=?9,es

Page <0

to '=*;788=?9&o

and '=*;7)(9,es

to '=*;7)(9&o

and '=*;7'EB)D:NE*)9&o

to '=*;7'EB)D:NE*)9,es

If we are enabling websockets, we $ust also install the websockets libraries ee the following for instructionshttps-..libwebsocketsorg.inde4ht$l In su$$ary, we clone a git pro6ect, within the pro6ect directory create a directory called *build*, in the build directory e4ecute * cmake 55* and when that co$pletes, e4ecute a *make* against the akefile that was 6ust built for us (his install needs c$ake which can be installed via$ sudo apt-get i&stall cmake

Installing on Windows

!e can download and install a version of Mos/uitto for !indows +inary downloads are available herehttp-..$os/uittoorg.download. (he version illustrated here is 1CB

Page <1

Page <2

Page
riting #/&& clients Having an MU(( environ$ent available is nice but without clients doesn't add $uch value Nour clients will be the applications that will register subscriptions and publish $essages (he subscriber will na$e the topic on which $essages published will be received

!hile the MU(( protocol $ay be standardi%ed, the client #PIs appear to not be #s such there are $ultiple #PIs for any given language Eclipse paho

ee also•

Paho ho$e page

•

Practical MU(( with Paho

C – Mosquitto client library

(he library called libmosUuitto is available for linking with  applications Nou will need to install the package called libmosUuitto-de/

•

mosUuitto7lib7/ersio& L Eeter$ine the version of the library in use

•

mosUuitto7lib7i&it L Initiali%e the library

•

mosUuitto7lib7clea&up L onclude the use of the library

•

mosUuitto7&e% L reate a client

•

mosUuitto7destro, L Eestroy a client

Page <

•

mosUuitto7rei&itialiCe L Eestroy a client and then create a new one

•

mosUuitto7user&ame7p%7set L et the userid and password for authentication

•

mosUuitto7%ill7set L et the last will of the client for estate planning purposes

•

mosUuitto7%ill7clear L "evoke the last will

•

mosUuitto7co&&ect L onnect a client to a broker 

•

mosUuitto7co&&ect7bi&d L a$e as mosUuitto7co&&ect but constrains interface to bind with

•

mosUuitto7co&&ect7as,&c L #synchronous connection to the broker 

•

mosUuitto7reco&&ect L "econnect to a broker after a lost connection

•

mosUuitto7reco&&ect7as,&c L a$e as mosUuitto7reco&&ect but asynchronous

•

mosUuitto7disco&&ect L Eisconnect a client fro$ a broker 

•

mosUuitto7publis L Publish a $essage on a given topic

•

mosUuitto7subscribe L ubscribe to $essages on a topic

•

mosUuitto7u&subscribe L 7nsubscribe to $essages on a topic

•

mosUuitto7loop L Perfor$ processing for the mosUuitto client It is here that inco$ing $essage fro$ the broker are received or previously unsent publications trans$itted

•

$os/uittoTloopTread

•

$os/uittoTloopTwrite

•

$os/uittoTloopT$isc

•

mosUuitto7loop7fore/er L a$e as mosUuitto7loop but does not return and keeps processing until the client is disconnected

•

mosUuitto7socket L "etrieve the low level (P.IP socket that the mosUuitto client is using

•

mosUuitto7%a&t7%rite L "eturn true if there is pending data to be sent to the broker 

•

mosUuitto7loop7start L tart a thread to process a mosUuitto7loop in the background

•

mosUuitto7loop7e&d L top a previously started loop that was created using mosUuitto7loop7start

Here is an e4a$ple publishing clientFi&clude stdio5J Page <$

Fi&clude stri&g5J Fi&clude mosUuitto5J i&t mai&.i&t argc car Rarg/ST  car Rost9"pc#100"Y i&t port 9 1GG3Y car Rmessage 9 "ello %orldK"Y car Rtopic 9 "greeti&g"Y

   

    

mosUuitto7lib7i&it.Y struct mosUuitto RmosU 9 mosUuitto7&e%. >8AA  8AAY  >o callback param i&t rc 9 mosUuitto7co&&ect. mosU  :lie&t a&dle ost  ;ost of te broker port  Port of te broker falseY  >o keepali/e if .rc K9 D)M7E((7)8::E))  pri&tf."Error %it co&&ect d^&" rcY retur&.rcY  mosUuitto7publis. mosU  :lie&t a&dle >8AA  essage id topic  *opic strle&.message]1  Ae> of message .co&st /oid Rmessage  essage to be se&t 0  Mo) 9 0 falseY  >ot retai&ed mosUuitto7destro,.mosUY mosUuitto7lib7clea&up.Y

ee also•

$an839 L lib$os/uitto

•

$os/uittoh

Node.s !a"a#cript – M$%%

(here is ode6s package called mUtt that provides MU(( functions for ?avacript applications (o install this package we should run$ &pm i&stall mUtt

Here is a sa$ple ?avacript application that acts as a publisher/ar mUtt 9 reUuire."mUtt"Y /ar clie&t 9 mUtt5co&&ect."mUttpc#100"Y clie&t5o&.Wco&&ectW fu&ctio&.  co&sole5log.":o&&ected 555 &o% publisi&g"Y clie&t5publis."greeti&g" ";ello from a/a)cript"Y   clie&t5e&d.Y Y

 #nd here is an application frag$ent that acts as a subscriberPage <)

/ar mUtt 9 reUuire."mUtt"Y /ar clie&t 9 mUtt5co&&ect."mUttpc#100"Y clie&t5o&.Wco&&ectW fu&ctio&.    clie&t5subscribe."greeti&g"Y Y clie&t5o&.WmessageW fu&ctio&.topic message  co&sole5log."(ecei/ed message for topic9" ] topic ] " message9" ] messageY Y

rror handling can be acco$$odated by registering a client handler for an error eventclie&t5o&."error" fu&ctio&.error  co&sole5log."'e detected a& error " ] errorY Y

(he full details of the #PI can be found on the PM ho$e page for the MU(( package #t a high level, the functions are-

•

co&&ect L onnect to a broker

•

:lie&t5publis L Publish a $essage (he $essage content $ay be a Buffer or a stri&g (he identity of the topic on which the $essage is being published $ust also be supplied

•

:lie&t5subscribe L ubscribe to a topic

•

:lie&t5u&subscribe L 7nsubscribe fro$ a topic (he signature is-

clie&t5u&subscribe.topic Soptio&sT ScallbackT

•

:lie&t5e&d L lose the client connection to the broker

•

:lie&t5a&dleessage L # $echanis$ for handling $essages

ee also•

np$ L $/tt

Browser !a"a#cript – M$%%

(he clipse Paho pro6ect includes a ?avacript client #PI that is suitable for running within the conte4t of a browser (his client #PI uses the H(M:2 !ebocket #PI to co$$unicate with an MU(( broker

Page <,

(he MU(( broker chosen $ust support MU(( protocol through !ebocket Popular brokers such as Mos/uitto are able to perfor$ that role Fro$ a security standpoint, browsers are only allowed to $ake !ebocket re/uests back to the H((P server fro$ which the page running in the browser was originally loaded #s such, the browser can only $ake !ebocket re/uests to the MU(( broker if the MU(( broker served up the page !e can alleviate that issue by introducing full function !eb ervers and pro4ies into the story but for si$ple purposes, brokers such as Mos/uitto can serve up static web pages directly (his $eans that we can point our browser to Mos/uitto which will then look for an H(M: file on the local file syste$ to Mos/uitto and send that back to the browser (he browser will now see the MU(( broker as the server of the web page and when the ?avacript in that web page asks for an MU(( subscription, it will succeed !ithin the Mos/uitto configuration file, each listener definition that wishes to also provide H((P files $ust supply an * ttp7dir* option which na$es the directory that will be searched for H(M: file re/uests fro$ the browser !e are not li$ited running an MU(( broker on a separate server $achine, we can run the MU(( broker directly on the Pi should we desire ow let us look and see what is needed to run an MU(( client in the browser First we need to download the Paho ?avacript client If we visit the Paho downloads pagehttps-..pro6ectseclipseorg.pro6ects.technologypaho.downloads we will find an entry for *?avacript client 101* Follow through that link and download the GIP file #t the ti$e of writing the result will bepao5Ia/ascript-150515Cip

we can then un%ip the file using u&Cip !ithin we will find a file called mUtt%s315Is (his is the ?avacript source of the client and needs to be included in the H(M: file that will be using MU(( Here is an e4a$ple H(M: with e$bedded ?avacript illustrating us connecting to a broker and registering a subscription !hen a $essage is published to the $atching topic, it is logged to the browser console tmlJ   eadJ Page <<

script src9"mUtt%s315Is"JscriptJ   scriptJ /ar clie&t 9 &e% Pao5M**5:lie&t."1#251HG515101" G0G1 "" ":A=E>*1"Y clie&t5o&essage+rri/ed 9 fu&ctio&.message  co&sole5log."essage arri/ed 555 " ] message5pa,load)tri&gY Y clie&t5o&essage?eli/ered 9 fu&ctio&.message  co&sole5log."essage deli/ered 555"Y Y clie&t5co&&ect. o&)uccess fu&ctio&.  co&sole5log."D& success 555 %e are &o% clie&t co&&ected to te brokerK"Y clie&t5subscribe."greeti&g"  o&)uccess fu&ctio&.  co&sole5log.")ubscriptio& success 555"Y  o&ailure fu&ctio&.co&text error:ode  co&sole5log."ailed to make a subscriptio& 555 code9" ] error:odeY  Y  o&ailure fu&ctio&.co&text error:ode erroresage  co&sole5log."D& failure 555 code9" ] error:ode ] " message9" ] erroresageY  Y   scriptJ   eadJ   bod,J   bod,J tmlJ

!ithin the mosUuitto5co&f file, we will have an entry that looks likeliste&er 1GG3 protocol mUtt liste&er G0G1 protocol %ebsockets ttp7dir m&tpcproIectsrobot

(his defines that we will listen on port 1BB3 for standard MU(( protocol while we will also listen on port B0B1 for websocket H((P re/uests and if a re/uest to load a page arrives, we will serve it fro$ a given directory (he #PI to publish a $essage is called *send* and takes as a para$eter an MU(( $essage ob6ect ee also•

clipse Paho ?avacript client

•

Paho #PI ?avacript docu$entation

•

(he Mos/uitto MU(( broker gets !ebsockets support

Page <9

4thernet !hile the HIP by itself does not support thernet, there is a plugin board available which adds an thernet connection (he board is called *Hu$$us* and is available fro$ hip Eip hop-

ee also•

hip Eip hop L Hu$$us

56.indows :inu4 has a graphical user interface called J)!indows !hen you start :inu4 and connect your HIP to a (D, it is J)!indows that provides the graphical environ$ent into which you can open windows and run other graphics oriented applications 7nlike other graphics syste$s, J)!indows was designed to operate in a client.server $ode ince 7ni4 is a $ulti)user environ$ent, it isn't reasonable to think that all users could sit around the sa$e graphics ter$inal so a $echanis$ to run one's applications on 7ni4 while having the graphical results displayed on a local ter$inal was needed (he J)!indows environ$ent provides a client.server architecture In that $odel, the client is the application that wishes to display graphics and the server is the software or hardware that the client draws upon It is the server that an end user sits in front off

Page 90

It is likely you have a P as your nor$al workstation environ$ent that includes a $onitor, keyboard and $ouse I like to use this as $y environ$ent for working with HIP In order to do such, I run an J)!indows server on $y windows P, open an H connection to $y HIP, point the J)!indows output back to $y P and then start the HIP J)!indows desktop (he result of this is a window on $y P which is the desktop of HIP (his allows $e to sit in one seat and switch between working on the HIP and working on the P  #lthough the HIP is fantastic, it will be unlikely to be anywhere near as powerful as your P which is likely loaded with your favorite browser and other goodies n $y !indows P, I use the free version of 4$ing 8 http-..sourceforgenet.pro6ects.4$ing.9 to run a local J)erver (o start the HIP desktop on the J)erver output, use xfce4-sessio& !hen the device running an application wishes to display its output on an J)!indows server, the application has to know which J)!indows server to use #fter all, an J)!indows server is $erely an application sitting at the end of (P.IP connection (he way to tell the application where to send the graphics re/uest is through an environ$ent variable called ?=)PA+L (he for$at of the variable is ;D)* or =PJ)cree&J ince an J)!indows server can display $ultiple screens, we specify which screen to use << ti$es out of 100 we want to use 0 Here is an e4a$ple of use$ export ?=)PA+L91#251HG51520 $ xfce4-termi&al

J)!indows provides a level of security configuration to prevent any arbitrary co$puter fro$ accessing your screen 8note that this $eans reading your screen as well as writing to it9 n your J)!indows server environ$ent, you can control this by running the *xost* co$$and I typically run * xost ]* which allows any $achine on $y local network to access the J) !indows server (his should nor$ally not pose an undue security risk as $y J)!indows servers are on $y local :# inside $y house and there is no inbound route to $y J)!indows servers through $y router . firewall fro$ the Internet

Using )ming on a .indows PC n $y !indows 10 P, I run the free application called xmi&g (his is an J)!indows server  that perfor$s all the tasks I $ight need (o start it I run J:aunch which then presents $e with a series of options (he following i$age shows the first screen-

Page 91

ince J)!indows is itself a windowing environ$ent and we are already running on a windowing environ$ent 8Microsoft windows itself9, we have the option of how to $ap the two together (he choice here is a $atter of taste I prefer the one window flavor

Page 92

(he ne4t screen asks us whether or not we want to start a re$ote application when xmi&g starts I usually select no

Page 9/

(he ne4t screen is about server settings I want clipboard copying enabled and I also disable access control

(he final screen allows us to start the server and optionally save the configuration nce done you will see the J)!indows server background which is a dull checkerboard like appearance-

!hat re$ains for you to do now is connect into your HIP and run xfce4-sessio&

Using moba5term on a .indows PC  #n alternative to xmi&g is the !indows based $ oba@term (his has a personal edition which is free of charge (his tool provides an elegant co$bination of J)erver plus shell login Page 9

plus file browsing and a host of other features !hen started, we can select to attach to a re$ote :inu4 syste$

nce selected, we are presented with a very nice ter$inal e$ulator which is set up for J clients and provides a file browser-

If we launch an J application, it opens in its own !indows window Personally, I choose to Page 9$

specify that we create a single desktop window in which other J)!indows open !e do that in the configuration settings-

 #nother tip when using $obaJter$ is to create a $acro for starting the desktop # $acro is a recording of keystrokes.co$$and that can be played back fro$ a $enu selection I create a directory called *bin* in $y ho$e directory and in there create a shell script that I call *ru&x5s* In that script I codeFKbi&bas &oup xfce4-sessio& J de/&ull 2J de/&ull 

(his causes the desktop window $anager to startup in the background I then create a $acro that runsbi&ru&x5s

and then when I start an H session into HIP, I find a $enu entry for the $acro-

which starts the HIP J)!indows desktop (his saves keystrokes, typing errors and having to re$e$ber co$$ands ee also• Page 9)

Nou(ube- HIP (utorials- 7sing $obaJter$ with HIP

Building 5 applications If we wish to build 7I applications 8such as J)applications9 then the A(5 toolkit is what we want to use (here is a screen designer called *glade* that $akes the 6ob easier for us !e can install this with$ sudo apt-get glade

Customi7ing the 5 desktop JF is an J)!indows desktop environ$ent and is pre)installed on the HIP (he overall appearance of the desktop can be configured as a group of settings called a *style* (he default style used by hip is called *hip* I a$ personally not a fan (oo dark and too pink Fro$ the applications $enu, we can launch )etti&gs J +ppeara&ce and change our styles-

If we change the style, for e4a$ple to *Jfce)dawn*, then the whole set of windows look and feel change-

Page 9,

(he desktop is the background against which we perfor$ work !e can change its configuration by launching the *Eesktop ettings* application-

Here we can change the background i$age, colors, $enu content and icons  #fter $aking such changes, you will end up with a look and feel of your own preferences-

Page 9<

Eon't be afraid to e4peri$ent and tinker with the ad6ust$ents until you end up with the desired result  #t the top of your display is a bar called a * pa&el* (his is actually the application called *xfce4-pa&el* It is a container used to show icons of currently open applications, launch $enus and a variety of widgets ite$s If we wish to add new ite$s to the panel, we bring up its conte4t $enu and select * +dd >e% =tems_*-

7pon selection, a list of the available ite$ types are shown !e can select these and add the$ to the panel-

Page 99

!e can see the current widget ite$s already on the panel by selecting *Panel Preferences*-

and then selection the *Ite$s* tab-

Page 100

(he order of the ite$s can be changed as well as adding or re$oving ite$s If a widget has custo$i%ation properties, they too can be edited in this page !e are not li$ited to 6ust one panel !e can add additional panel instances and position the$ as we like For e4a$ple, we can have a bar at the top and a second bar at the botto$ !hen the desktop starts, we are presented with the HIP splash screen that looks as follows-

!e can replace this splash screen with any i$age we desire 8or even none at all9 If we launch the ettings W ession and tartup tool we see the following-

Page 101

Fro$ here we can custo$i%e the i$age by clicking the *onfigure* button-

(he i$age file used for the splash screen can be selected If you change it to any i$age on the file syste$, that i$age will be used for the splash !e can add our own applications and directories to the desktop !e do this by creating a new file that is read by the desktop $anager (he content of the file is described in a *desktop)entry)spec* specification docu$ent 8see references9 (o $ake your own entries, create a new file in the *Eesktop* folder in your ho$e directory (he e4tension of the file should be *desktop* !ithin the file we have *sections* and *properties* # section is a na$e surrounded in s/uare brackets For e4a$pleS?esktop E&tr,T

and properties are na$eQvalue pairs For e4a$pleersio&9150

(he $andatory entries arePage 102

Property Name Description

 =ae

The nae o the entry on the deskto!.

Ty!e

The ty!e o the deskto! entry. %llo"able alues areK •  – %n a!!lication to launch.

• •

+pplicatio& Ai&k – 8ink to a "eb !age. ?irector, – % directory to naigate to.

The ile ty!e or this entry should be L.directoryL as

o!!osed to L.deskto!L.

o$e of the $ore co$$on properties includeProperty Name Description

6ec

The !rogra to launch i the user asks to run the !rogra.

Path

The "orking directory o the a!!lication "hen launched.

Terinal

7hether the a!!lication runs in a terinal.

U'8

:andatory !ro!erty or deskto! entries o ty!e LlinkL.

Icon

The icon to use to re!resent the entry on the deskto!.

Coent

% toolti! hel! tet that is sho"n i the user hoers oer the icon.

(he default location for syste$ *desktop* files is .usr.share.applications (he icon i$age types supported are *png* and *svg* ee also•

4fceorg

•

Jfce Panel

•

(he$es for JF L www4fce)lookorg

•

desktop)entry)spec specification

•

Eesktop entries

"unning Headless (he ter$ *headless* si$ply $eans that your HIP doesn't have a display, keyboard and $ouse connected to it (his then begs the /uestion of *How do I interact with the HIP if it is headless* (here are a couple of answers to that pu%%le, the $ost co$$on ones being-

•

onnect the HIP to a (P.IP network 8eg !iFi9

•

onnect the HIP via a serial cable

Using your PC as a graphical CHIP desktop (he HIP is a great little co$puter but the chances are high that you have another co$puter Page 10/

that you co$$only sit at (his $ay be a !indows P, a Mac or a :inu4 $achine (his P will likely have a $ouse, keyboard and $onitor attached !ouldn't it be great if you could interact with your HIP through that P (here are a nu$ber of choices available to us to achieve that task (he first one we are going to look at is running an J)!indows server on the P and opening windows fro$ your HIP on the J)erver (here are a wide variety of free J)ervers that run on Ps My favorite is *moba@term* !hen you install and run this package on !indows, you can open an H session fro$ the P to HIP and get a ter$inal co$$and pro$pt Fro$ there, you can run the co$$and * xfce4-sessio&* which will start a desktop on your P +y default, when you boot HIP, it starts a local J)erver If you are re$otely connecting into HIP, there is no need to run this as it consu$es syste$ resources (o prevent HIP fro$ loading an J)erver at boot, we can can run the following co$$and$ sudo s,stemctl set-default multi-user5target

(he ne4t ti$e HIP is restarted, we will be left at the login pro$pt (o re)enable the graphical environ$ent, run the following co$$and$ sudo s,stemctl set-default grapical5target

ee also•

7sing $obaJter$ on a !indows P

•

7sing 4$ing on a !indows P

Connecting to CHIP using a serial connection Many ti$es I find $yself on an airplane or in a hotel roo$ with a laptop and a HIP 7nfortunately, I can't play with $y HIP for a variety of reasons ither I have no !iFi environ$ent, no roo$ for a keyboard or a$ otherwise short so$ething ow i$agine I could attach $y HIP to $y laptop via a short 7+ cable nce connected, I could then open up a ter$inal e$ulator on the laptop such as Pu((N which would then show a login to the HIP Fortunately, we can do 6ust that using the 7#"( of the HIP connected to a 7+X7#"( adapter (o deter$ine if the 7#"( is being used as a ter$inal, run$ s,stemctl status serial-gett,Vtt,)0 X serial-gett,Vtt,)05ser/ice - )erial
Fro$ this we can see that a gett, instance is running

Page 10

For e4a$ple, if we take a P10 7+ to 7#"(-

 #nd connect the (J pin of the 7+X7#"( to the "J pin of the HIP and the "J pin of the 7+X7#"( to the (J pin of the HIP, then if we run Putty against the M port that shows up in !indows, we get a :inu4 login pro$pt (here are a nu$ber of good serial ter$inal applications available, one of the $ost popular is Pu((N which is available for both :inu4 and !indows !e can install this on HIP by installing the package called * putt,* Pu((N is an J)!indows application so will need an J) erver on which to display the output My favorite connection tool, $obaJter$ also provides a serial connection capability-

ee also•

7#"( on HIP

•

7sing $obaJter$ on a !indows P

Page 10$

Connecting to CHIP using the U%B cable (he 7+ cable that one uses to power HIP can si$ultaneously be used to co$$unicate with it !e plug the $icro 7+ end into the $icro 7+ socket on HIP and plug the other end into a :inu4 based P If all has gone well, running *lsusb* on :inu4 will show an entry that containsBus 001 ?e/ice 021 =? 0!2!a4aa >etcip *ec&olog, =&c5 Ai&ux-8)B :?: :omposite
!hat this $eans is that the cable connection will show up as both a network connection and a serial connection !e will focus on the serial connection for 6ust now :ook for a directory entry called .dev.tty#M0 on the :inu4 P If found, then that is an 11200 baud connection to HIP If we install and run a ter$inal e$ulator such as *putty*, we will connect to HIP

nce connected, we will see a HIP login-

Page 10)

V,C – Virtual ,etwork Computing D is a technology that allows one to see the desktop of one $achine fro$ another For e4a$ple, if HIP is showing graphics output on the screen, then D can be used to $irror that output to another co$puter such as your P (here are a nu$ber of i$ple$entations of D available, the two $ost prevalent being-

•

"eal D

•

(ightD

(o get started, we $ust install a version For e4a$ple$ sudo apt-get i&stall tigt/&cser/er

nce installed, we need to run tightvncserver to create a login password and an optional view only password (o start the D server we can run * /&cser/er* (o see if the D server is already running, we can use * ps -ef | grep -i /&c* :ook for processes that are called * @tigt/&c* ach one of those is an instance of a D srever otice also the display nu$ber that follows it Here is an e4a$ple$ ps -ef | grep -i /&c cip 2242 1 2 2116 pts1 000000 @tigt/&c 1 -desktop @ -aut omecip5@autorit, -geometr, 1024x6HG -dept 24 -rfb%ait 120000 -rfbaut omecip5/&cpass%d -rfbport !#01 -fp

Page 10,

usrsarefo&ts@11miscusrsarefo&ts@11*,pe1usrsarefo&ts@116!dpiusrsar efo&ts@11100dpi -co etc@11rgb cip 22#2 1#0G 0 2116 pts1 000000 grep -i /&c

!e can stop the D server with/&cser/er -kill displa, idJ

for e4a$ple$ /&cser/er -kill 1

o$e of the $ore i$portant para$eters to vncserver include-

•

-geometr,

widthxheight L

et the di$ensions of the screen to width pi4els by

height pi4els nce a D server is running, the ne4t thing to do is connect to it fro$ another $achine (his can be a P, tablet or even a phone In fact anything that runs a D client will work (he D clients can be obtained at the D provider links above Here is an e4a$ple of using a (ightD client to connect to the D server on the $achine chip listening on port 2<01-

Page 10<

!hen the *onnect* button is clicked, we are pro$pted for the login password we created earlier-

Here is the sa$e using "ealD-

Page 109

f the clients available and the ones I have played with, "ealD is $y personal choice ee also•

D 8Dirtual etwork o$puting9

•

$an819 ) vncserver 

Programming !hat is a co$puter if not for progra$$ing +efore we get into progra$$ing proper, let us first talk about editing source files # source file is the source code of your application that will then be run o$e languages re/uire that the source be co$piled into e4ecutables 8eg 9 while others interpret the source code 8?avacript, shell, Python9 In both cases, we need to use an editor to edit the source (he choice of editor is as $uch personal preference as anything in our I( world If I said use editor JNG, so$eone else would i$$ediately turn around and say that we should use editor #+ (he best I can offer is a short list of so$e of the $ore popular editors and let you take your pick (he /i editor is the historic te4t based editor that has been around for $any decades o$e users love it, and so$e hate it It is definitely not for the 7ni4 beginner Its co$$ands are cryptic If you know /i today, aweso$e & if you don't know vi, then I would not reco$$end it as the editor to learn Its strength today is predo$inantly that it is ubi/uitous across every known 7ni4 variant (he &a&o editor is another te4t editor and this is significantly easier to use than /i (he $anual page and.or the editor docu$entation should be consulted for details & however the basic $odel is to use the cursor keys and enter.change.delete te4t

Page 110

(he gea&, editor is perfect for editing code in an J)!indows environ$ent It includes language knowledge as well as build co$$ands I use gea&, $ost of the ti$e for $y own editing when editing locally

Page 111

o far we have assu$ed that we are editing files directly on HIP and also that our source lives on the HIP device !hile that is certainly a solution, if you are working on a large pro6ect, I $ight caution against that for a nu$ber of reasons Firstly, reali%e that the source of  your applications represent hours and hours worth of work How would you feel if you accidentally deleted your files and couldn't recover the$ !hat if your files si$ply got *lost* !hile the HIP is a fantastic device, it doesn't have the $aturity of a desktop P (here is no recycle bin to recover your files if you hit delete #lso, since you are likely building a pro6ect that $ay involve so$e hardware interfacing, consider that all too co$$on *oopsie* where you plug a wire into the wrong socket n the HIP, that could fry your board (hankfully, since the HIP only cost ;<, you can si$ply get another one  but what of all your work locked up in the flash $e$ory of the device h h>>> o re$ovable storage to take out and place in a new device uch>>> Instead, I reco$$end editing and saving your source on a desktop operating syste$ Personally I use either !indows 10 or 7buntu My develop$ent environ$ent is clipse 8for , ?ava, ?avacript and !eb9 clipse has built in support for AI( and I regularly co$$it $y changes back to Aithub for secure storage and duplication as a backup and to return to a previous state 8if needed9 !ith $y source code on the desktop, I then e4port that directory for $ounting access on HIP HIP then treats that file syste$ with the illusion that it is local Page 112

and fro$ there I can do $y co$piles and tests (he source really lives on the desktop # side benefit of this techni/ue is that should I get low on HIP file syste$ storage, the source code, co$piled ob6ects and e4ecutables doesn't count against HIP storage since all data is re$otely held on the desktop

Programming in general ne of the e4citing aspects of the HIP environ$ent is that one is not forced to work in any particular progra$$ing language when building HIP applications ne has a wealth of choices available :anguages available include , KK, ?ava, ?avacript, Python and $ore o$e are $uch $ore co$$only used and prevalent than others and for so$e languages we even have $ultiple choices of co$piler and environ$ent to use !ith choice co$es decision !hen you wish to undertake a pro6ect, which language do you use Eespite what $any folks $ight argue, $y vote is to use the one you *want* to use 8where possible9 (he choice of one language over another can /uickly break down into a religious battle where personal bias holds as $uch argu$ent as technical $erits  #n early decision that you will $ake is whether you develop on HIP itself or on a P I a$ assu$ing that you have a !indows or :inu4 P available to you It is a safe bet that your P is going to be $uch $ore powerful than your HIP Nour P will be faster, have $ore "#M and have disk capacity to hold all the files you need My reco$$endation is to develop your applications on a P and either cross)co$pile or copy across for co$pilation the files and artifacts necessary ross co$pilation is the better option of the two !ith cross)co$pilation, you edit and co$pile your source code on the P and then test and run it on HIP (his gives you the power of a P for develop$ent and insulates you fro$ HIP crashes which are all too possible when working with low)level parts and electronics in general #ccidents can happen and if you short your HIP, then you will be restarting your environ$ent fro$ a fresh boot (he reduction in ti$e that it takes to perfor$ a build on a P is also very dra$atic

E1F structure !hen we co$pile an application on a :inu4 environ$ent for e4ecution, the result is a file containing e4ecutable instructions (he for$at of the file is known as the 4ecutable and :inkable For$at 8:F9 and contains a progra$ that *thinks* it has an address space of 040000& to Yn where n is either 3 or @C (he :F file contains logical sections which contain data for distinct purposes #$ong the sections are-

•

5text L Instructions for e4ecution

•

5data L Initiali%ed data (his could be data that can be read)and written to that has an initial value For e4a$ple-

i&t m,ar 9 123Y car Rm,)tri&g 9 ";ello 'orld"Y

• Page 11/

5bss L 7ninitiali%ed data (his is data that can be read and written to that has a %ero

initial value static i&t m,arY

•

5rdata L "ead)only data (his is data that can be read fro$ but not written to For e4a$ple-

co&st i&t m,ar 9 123Y pri&tf.";ello 'orldK^&"Y

It would not be sensible to believe that large applications can be written in 6ust one source file Instead, applications typically are broken up into $ultiple source files where the code in one file typically perfor$s so$e specific function In order for this to be useful to us, we $ust also allow code that e4ists in one source file to invoke code that $ay e4ist in a different source file (his brings us to the concept of e4posed sy$bols !hen we co$pile a source file to its ob6ect file representation, the resulting ob6ect file can e4pose the sy$bols of functions and variables +y e4posing these sy$bols, we can then find their $e$ory locations during link ti$e (he flip side of this is the concept that we can declare variables and functions in our source code as being defined elsewhere (his $eans that during co$pilation, these variables and functions will not be found but, at linking ti$e, the linker will ensure that so$ewhere in the aggregate of files being brought together, all undefined sy$bols are resolved to so$e defined sy$bol !e can use the &m co$$and to list the defined and undefined sy$bols within an ob6ect file or archive

1i!raries of code !hen you co$pile a  progra$, an ob6ect file is produced which is the co$piled representation of your  source It consists of instructions ready to be e4ecuted by the P7 nly when the ob6ect file is linked with the  run)ti$e does it beco$e an e4ecutable ow i$agine that you have authored so$e code that you want to use over and over again Perhaps it is a general logging function or so$e speciali%ed algorith$ for drawing graphics on the display !hen ever you want to re)use that code, you could include the source in your pro6ect, reco$pile it and link it with the rest of your application However this is not an opti$al idea for $any reasons First, you have broken your desire for encapsulation Nou can go into the source file of the function and tinker with it (his can $ake $aintenance a challenge as you will now have $ultiple distinct copies of the source floating around Nou will also be wasting co$pilation ti$e re)building the ob6ect file each ti$e you co$pile

 # better solution would be to co$pile the original source once and re)use the ob6ect file Page 11

directly when needed ow the ob6ect file beco$es an encapsulation of the function and can't be conta$inated with inadvertent tweaks It is also likely that you won't 6ust have one re) usable piece of function but instead have $any (his $eans that you $ay end up with do%ens of ob6ect files each of which need to be linked with your final application (here $ay also be dependencies between these ob6ect files and trying to re$e$ber which ob6ect files you need to pass to the linker can beco$e a challenge Fortunately, :inu4 provides an easy and elegant solution in the for$ of the supplied archiver tool called ar (he ar tool allows us to take a set of ob6ect files and aggregate the$ together  into a single file that we call an archive file +y :inu4 convention, the na$e of an archive file begins with *lib* 8for library9 and ends with the file suffi4 of * 5a* for archive If you are fa$iliar with taking $ultiple files and producing a GIP file, this is a si$ilar concept 8but without co$pression9 (he linker has knowledge of the $eaning of an archive file and when you add that to the co$pilation steps, references to sy$bols 8functions and variables9 will be sought within the ob6ect files contained within the archive (he end result is that you can group together useful libraries of function into a single archive file and $erely link with that *black bo4* to incorporate the function contained within into your own applications

Having spoken about building your own libraries, you should also reali%e that this story also applies to libraries that you $ay leverage fro$ others If a new whi%)bang pen ource library beco$es available, you can use the functions it e4poses in your own applications without having to know how they work !ith  progra$$ing, we have the need to define functions and variables which are not locally present within the co$piled app For e4a$ple, i$agine that you want to call a function called %iCBa&g. that is supplied in a library If you si$ply call %iCBa&g. fro$ your code, you should end up with a co$pile ti$e warning or error that the co$piler doesn't know anything about %iCBa&g. (he solution is to include a  language header file that contains the definition of the function For e4a$ple/oid %iCBa&g.car R&ame i&t ageY

Page 11$

(his gives the co$piler all the knowledge it needs to validate that a call to the function is as e4pected #s such, when a library is provided there should be one or $ore header files that are acco$panied with it that provide the relevant definitions to allow you to correctly use it

#tatic "s &ynamic libraries

o far we have been discussing what we will learn is called *static libraries* # static library is $erely a short)hand $echanis$ for distributing ob6ect files that are linked into your own application (he code contained within these libraries is copied into your application (his $eans that your application beco$es larger (his should not be a surprise as if you include new function in your application, you would e4pect it to beco$e larger However, there is an alternative story that we need to consider and this called the dyna$ic library (he notion of a dyna$ic library is that when you link your application with a library, instead of the code contained within that library being copied into your application, your application $erely re$e$bers that before it can e4ecute, the functions contained within that library need to be present (hey are not made present by copying the$ into the e4ecutable at link ti$er but are instead $ade present at run)ti$e by dyna$ically loading the$ fro$ the archive file into $e$ory at the start of e4ecution !hat this $eans is that your application is no longer 6ust one e4ecutable file but is instead the e4ecutable plus the set of archive files that need to be loaded (he benefit co$es with the notion that many applications $ay also be using the sa$e library ow instead of each application having a copy of the sa$e library 8and hence consu$ing $ore disk space9, all the applications will share the sa$e archive file (he result will be an overall saving of disk space when you have two or $ore applications that need the sa$e function (here is another $assive benefit also available !hen an application runs, it needs to have all its code loaded into $e$ory to operate If two applications are using the sa$e static library, they in effect each have a copy of the sa$e co$piled function !ith a dyna$ic library, the operating syste$ knows if the dyna$ic library has already been loaded If it has been loaded, it shares the in $e$ory e4ecutable code of that library across $ultiple applications through a techni/ue called $e$ory $apping (here is yet another benefit to shared libraries ince the shared library is kept in a file distinct fro$ the e4ecutable then if we replace the archive file with a new version then the ne4t ti$e the application is started, it will si$ply pick up that new version and start using it !hat this $eans is that if our library is changed to incorporate bug fi4es, those fi4es beco$e available to the new applications !ith static libraries, we would have to relink the application as a whole to insert a copy of the new code into the application file +y convention, shared libraries have the file suffi4 of * 5so* as opposed to * 5a* for static libraries

Building shared libraries

+uilding a shared library is not a co$ple4 task !hen co$piling your code, you need to add Page 11)

the additional co$piler flag called * -fP=:* (o aggregate the ob6ect ob6ect files files together into a shared library, we don't use the ar tool, instead we use the co$piler again adding the * sared* flag :et us look at the * -fP=:* flag PI is is an acrony$ for *Position Independent Independent ode* +y specifying this flag, we are indicating to the co$piler that is should produce code that is not dependent on where it will be loaded in the address address space of a process (his allows different applications to load the sa$e code at different $e$ory locations since each application $ay have its own needs as to where code is found

General development tools ar

!ork with the content of an archive file file #n archive file can be thought of as a container for for other files !hen we are working with  source files and co$pile co$pile those to ob6ect files, we could end up with hundreds and hundreds of such ob6ects to be $anaged (o $ake our lives easier, we can aggregate these ob6ect files together and place in an archive and then treat that archive as a single unit (o create an archive and populate it, we can use the followingar cr/ arci/e>ameJ SmembersJ 555T

ee also•

$an819 L ar 

•

7IJ ar 4a$ples- How (o reate, Diew, 4tract, Modify  #rchive Files 8Za9

ldd

(he ldd tool shows the shared library dependencies upon an e4ecutable ee also•

$an819 ) ldd

nm

(he &m co$$and can be e4ecuted against an ob6ect file or an :F e4ecutable to display the sy$bol tables contained contained within ontrast this co$$and with obIdump (he obIdump co$$and displays $e$ory layouts while the &m co$$and displays sy$bol table layouts o$e of the $ore i$portant flags are-

•

unde fined sy$bols only only --u&defi&ed-o&l, L Eisplay undefined

•

only --defi&ed-o&l, L Eisplay defined sy$bols only

•

--pri&t-file-&ame L Prefi4 each sy$bol with the file it co$es fro$

Page 11,

ee also•

$an819 L n$

obdump

(he obIdump co$$and can be e4ecuted against an ob6ect file file or an :F e4ecutable It du$ps and disasse$bles these files with a wife variety of options o$e of the $ore i$portant flags are-

•

--sectio&-eaders L Eisplay a su$$ary of the sections contained in the file

ee also•

$an819 L ob6du$p

ranlib

ee also•

$an819 L ranlib

readelf 

ee also•

$an819 L readelf 

C Programming ince HIP runs the :inu4 operating syste$ and :inu4 :inu4 is a version of a 7ni4 and 7ni4 is heavily based on the  language, we $ust i$$ediately i$$ediately start thinking about  (he  co$piler is supplied in the package called * build-esse&tial*  #fter installation, we can now co$pile co$pile  progra$s For e4a$ple, create the following in a file file called *test5c*Fi&clude stdio5J /oid mai&.i&t argc car Rarg/ST  pri&tf.";ello %orldK^&"Y 

o$pile this with$ cc -o test test5c

and run the resulting progra$ with$ 5test

Page 11<

Nou have 6ust edited, co$piled and run a  progra$ (hat wasn't hard

pkg-config !hen we co$pile  progra$s, we co$$only have to supply definitions, include directories, flags and libraries with with which to link ince we can't absolutely guarantee where these files and definitions will be found, this this results in our Makefiles being co$ple4 Fortunately, Fortunately, there is an e4cellent tool called * pkg-co&fig* (his co$$and can be run in the steps of the co$piler to provide environ$ent specific details ach package that you $ay $ay want to use in your develop$ent has a *5pc* file associated with it

 # well well behaved library will provide its own *5pc* file (o see a list of such files, run$ pkg-co&fig list-all

!e can use pkg)config within $akefiles For e4a$ple, here is so$e usage that inserts the correct libraries and headerslibsoc-i&put libsoc-i&put5c $.:: -o $V $ $.sell pkg-co&fig --libs --cflags libsoc

ote that pkg-co&fig is not installed by default, you $ust install the package called * pkgco&fig*$ sudo apt-get i&stall pkg-co&fig

ee also•

Auide to pkg)config

•

$an819 L pkg)config p kg)config

1a'a%cript Programming ?avacript is a language that was originally invented as a scripting language running in browsers ven today that is still predo$inantly the case case It is an interpreted language language that has leanings towards ?ava but is sufficiently different that it is very $uch in a class of its own (here are $any schools of thought thought and opinions on ?avacript It is a loosely typed language which $eans that one doesn't have to declare variables before using the$ (his can result in tricky pu%%les to track down at run)ti$e that would have been caught with other languages at develop$ent ti$e For e4a$ple/ar sale 9  &ame "%idget" price 12534 Y sale5cost 9 sale5cost ] taxY

would not catch the $istake that we originally na$ed the property in sale as price but referred to it as cost nly at run)ti$e when the state$ent was was reached would we catch it Page 119

However, discussions along those lines tend to result in religious views and we will leave those alone Fro$ the perspective of HIP, HIP, there are also non)browser variants of the language including ode6s and ashorn that are at our disposal

2ode34s ode6s is not pre)supplied with HIP and $ust $ust be $anually installed #n ar$v= distribution is available (he following recipe illustrates illustrates an e4a$ple of installing ode6s on HIP$ $ $ $ $ $ $

cd tmp %get ttps&odeIs5orgdist/ ttps&odeIs5orgdist/45456&ode-/45456-li&ux-arm/6l 45456&ode-/45456-li&ux-arm/6l5tar5xC 5tar5xC tar -x/f &ode-/ersio&J5tar5xC cd &ode-/ersio&J sudo cp -( R usrlocal &ode -/ &pm -/

ode6s is evolving as the underlying ?avacript evolves # web web site called nodegreen contains a list of ?avacript features by availability within versions of ode6s (here is also a tool that will $anage $anage our ode6s environ$ents for us (he tool is called *&/m* (o install this, one would run$ %get -UD- ttpsra%5gitubuserco&te&t5comcreatio&ix&/m/053156i&stall5s ttpsra%5gitubuserco&te&t5comcreatio&ix&/m/053156i&stall5s | bas

 #lways check the pro6ect ho$e page to find the latest latest version of * &/m* nce installed, we can install $ultiple versions of node (he latest can be installed with$ &/m i&stall &ode

(o see which versions ve rsions are installed use$ &/m ls

(o switch to using the syste$ version 8the one that is syste$ defined9 d efined9 run$ &/m use s,stem

(o use a specific s pecific version use$ &/m use /H5!50

ee also•

 #dafruit L !hy node6s node6s

•

ode6s L ho$e page

•

Nou(ube- Installing ode6s

•

Aithub- creationi4.nv$

N'M

PM is the ode Package Manager which is a tool and environ$ent for packaging ?avacript libraries for distribution In si$ple ter$s, an PM package is a directory which contains Page 120

?avacript plus a control.configuration file called package5Iso& ontained within package5Iso& is the $eta)data $eta)data about the package itself itself ven if we are creating a local application, it is still very useful to create a package5Iso& (he content of the file is a ? ob6ect "&ame" "m,package" "/ersio&" "15050" "depe&de&cies"  ")omePackageJ" ")omeersio&J"  

!e can update the current packages For e4a$ple, running $ &pm outdated

will list the latest versions $ &pm update

will update the packages to the latest versions $ &pm ls

will list the packages installed for your application $ &pm u&i&stall packageJ

will re$ove a package $ &pm pru&e

will re$ove packages that are no longer referenced by your package6son (o install a package globally$ &pm i&stall packageJ -g

!hen we are building a $odule that will be included be reUuire., we should reali%e that an ob6ect In our ?avacript that i$ple$ents the $odule, the ob6ect reUuire. will return an called *exports* is the one that will be returned o if we create a ?avacript source file called *i&dex5Is* and in that source file codeexports5m,u&ctio& 9 fu&ctio&.  co&sole5log.";ello %orldK"Y 

(hen the ob6ect returned fro$ a reUuire. of our package will contain a function called *m,u&ctio&.* which, when called, will print to the console e$antic versioning is used to indicate the nature of changes ew pro6ects should start with 100 maIorJ5mi&orJ5patcJ

•

maIor changes are not backwards co$patible

•

mi&or changes add new function

•

patc changes fi4 proble$s

Page 121

ee also •

PM ho$e page

Writing an N'M module

(here $ay co$e a ti$e when you wish to write your your own PM $odule Maybe that is because you wish to turn your pro6ect into re)usable co$ponents or else wish to publish co$ponents for others to re)use Fortunately, Fortunately, it is not difficult Nou start by creating a file called * package5Iso&* (his is the the control file file for your $odule which provides its na$e, contents, version and other relevant relevant infor$ation (he content of the the file is a ? string It can contain the following properties 8$ost of which which are optional9-

•

&ame L (he na$e of the package that $ust be supplied by a consu$er of the $odule in a re/uires89 state$ent

•

/ersio& L (he version of this $odule in the for$ * x5,5C*

•

descriptio& L # description of the $odule

•

depe&de&cies L ther PM $odules that $ust be present for this $odule to operate (his is a very i$portant entry entry It is an ob6ect that has properties where each property na$e is the na$e of another PM $odule and the value is the version of the dependency re/uired (he encodings for it are-

◦ /ersio& L (he e4act version ◦ J/ersio& L Areater than the version supplied ◦ J9/ersio& L Areater than or e/ual to the version ◦ /ersio& L #ppro4i$ate version ◦ /ersio& L o$patible with version ◦ 1525x L o$patible with 10, 11 but not 134 or 04 ◦ Z L #ny version will do ◦ others  •

ke,%ords L # set of one or $ore keywords used by users to search in the PM repository to aid in finding this $odule

•

ho$epage

•

bugs

•

license

•

autor L (he identity of the author of the $odule

•

co&tributors L (he identities of contributors to the $odule

•

files

Page 122

•

$ain

•

bin

•

$an

•

directories

•

repositor, L (he repository where the source can be found For$ e4a$ple-

"repositor,"  "t,pe" "git" "url" "ttpsgitub5com&pm&pm5git" 

•

scripts L Darious scripts that should be e4ecuted

•

config

•

e&gi&es L (he versions of the environ$ent that the $odule will work upon

•

os L (he operating syste$ that the $odule will work upon

•

cpu L (he P7 architecture that the $odule will work upon

•

pri/ate L # boolean flag 8true or false9 that, if true, will prevent this $odule fro$ being published 8perhaps accidentally9 to PM

•

readmeile&ame L (he na$e of a file that is part of the package that will provide basic docu$entation (his is co$$only *"#EM$d*

In the ?avacript source file for your co$ponent, there will be a global variable provided to you called *exports* #ny functions or properties you add to that variable will be available to the user of the $odule (o publish a $odule to PM, you $ust login with your PM userid using$ &pm logi&

and fro$ within the directory that contains the $odule source, run$ &pm publis

!e can have the np$ tool create a package5Iso& file for us by running * &pm i&it* !ithin your i$ple$entation, you will find an ob6ect called * exports* Properties added to this will be available to the user of the package ee also•

reating ode6s $odules

•

package6son

5ohnny-Five !e can't talk about Io( devices like HIP and ?avacript without $entioning the ?ohnny)Five pro6ect Page 12/

(o build an environ$ent, install both chip)io and 6ohnny)five$ &pm i&stall cip-io Io&&,-fi/e

 # skeleton application will look like/ar fi/e 9 reUuire.WIo&&,-fi/eWY /ar cipio 9 reUuire.Wcip-ioWY /ar board 9 &e% fi/e5Board. io &e% cipio. Y board5o&.Wread,W fu&ctio&.   do o&&,-i/e stuff Y

!ithin the ?ohnny)Five fra$ework, we have now *nor$ali%ed* our co$plete interaction with hardware !e can now think of higher level $odules that work against specific technologies o$e are speciali%ed, so$e are generic !e will look at a few of these in the co$ing sections (he HIP headers e4posed by ?ohnny)Five are-

Page 12

If we need to switch on debugging, we can set the environ$ent variable * ?EB8<* to *cipio* ee also•

?ohnny)Five ho$e page

•

np$ L chip)io

%he 'in obect

In $y $ind, the Pin ob6ect is the work)horse of ?ohnny)Five (hrough Pin we can access all the I.s on the HIP header !hat this $eans is that we can both read and write the I. values fro$ these ter$inals !e create an instance of a Pin ob6ect with/ar pi& 9 &e% fi/e5Pi&."@=D-P0"Y

we have additional control by supplying options/ar pi& 9 &e% fi/e5Pi&."@=D-P0"  id   pi&   t,pe   mode Y

(he mode can be one of-

•

Pi&5=>P8* L (he pin is an input pin

•

Pi&5D8*P8* L (he pin is an output pin

•

Pi&5+>+AD< L (he pin is an analog input pin

•

Pi&5P' L (he pin is a P!M output pin

•

Pi&5)E(D L (he pin is a servo output pin

For our pri$ary consideration, we will initially only consider input and output If input, then we can read the value of the pin (o perfor$ a read, we would e4ecutepi&5read.fu&ctio&.error /alue   do someti&g %it te /alue 555 Y

ote that the read is an asynchronous operation If the $ode of the pin is output, we can set the pin value to either high or low (o set the pin high, we can callpi&5ig.Y

(o set the pin low, we can callpi&5lo%.Y

(o e4plicitly set either high or low, we can callPage 12$

pi&5%rite./alueY

where the value is either 1 or 0 corresponding to the desired signal

I(C with !ohnny )i"e

Many single board co$puters have a single I bus however HIP has three of the$ (he one that we $ost co$$only wish to work with is the one known as (!I which is found at de/i2c-2 (he board ob6ect has a $ethod called i2c:o&fig.optio&s that takes an ob6ect characteri%ing the I interaction #t a $ini$u$ it will have a property called *address* that identifies the address on the bus (he identity of the bus itself can supplied in the *bus* property which is a nu$eric For e4a$ple for I bus de/i2c-2 we would supply bus as 2

C*I' specific !ohnny )i"e obects

)tatusAed L (he power led on the board Maps to a *fi/e5Aed* =&ter&al*emperature L Maps to a * fi/e5*ermometer* Batter,oltage L Maps to a * fi/e5)e&sor*

I(C Component Bac+pac+s

HIP is $issing so$e interesting electronics technology such as PI and software serial however these capabilities are available through very cheap #rduino devices such as the  #rduino ano ?ohnny)Five has the concept of a *backpack* (his is an I interface between a HIP and an #rduino where the interfaces of the #rduino can interact with the hardware and ?ohnny)Five can then drive the #rduino with HIP based applications written in ?avacript driving ?ohnny)Five ee also•

Introducing I o$ponent +ackpacks

•

eoPi4els through ode6s.?ohnny)Five.#rduino I backpack

,ode6"4!hen we think about sensors, we /uickly find that we want so$ething to happen when a new reading is taken or so$ething changes Aenerically, we can look at this as co$$only being1 #ccept inco$ing event  Parse the content of the event 3 4a$ine the content Page 12)

C (est if the content $eets so$e criteria 2 ptionally do so$ething as a result of having e4a$ined and tested the content If we agree that, loosely speaking, this is a co$$on pattern then $aybe we can find a fra$ework that $akes processing this pattern easier !e are used to writing application logic that is driven by the arrival of an event (his logic is typically written in a progra$$ing language such as , ?avacript, Python or others #lthough not an inherent issue with the languages, when we look further at our pu%%le, we reali%e that these are generic progra$$ing languages and not any for$ of do$ain specific language & while what we have here is indeed a very specific do$ain & na$ely the processing of events It is not unco$$on at this point for yet another new progra$$ing language to be created !hether it is co$piled or interpreted, procedural, ob6ect oriented or functional are 6ust details of the language ode)"E has taken a different approach Instead of providing 6ust another language & it has provided the ability to describe the logic we want e4ecuted through a drag, drop and wire paradig$ ode)"E provides a drawing canvas onto which building)blocks called *nodes* $ay be placed (hese nodes can then be wired together such that the output of one node beco$es the input to the ne4t node down strea$ +y co$bing these nodes in a variety of different co$binations, we can achieve the goal we desire ode)"E co$es with a rich set of pre) supplied nodes and a growing library of co$$unity supplied nodes is also available If you don't find a node that suits or you have a very specific need, you can even aug$ent ode) "E with additional nodes of your own creation (he develop$ent environ$ent for ode)"E is the browser and hence no special software need be installed !hen one node passes control to another node, data is passed between the$ n node entry, the inco$ing data can be found in the ?avacript variable called * msg* which contains a property called *pa,load* that contains the body of the $essage # node can then $odify 8or create a new9 output ob6ect and that then beco$es the $essage passed on to the ne4t downstrea$ node In addition to the $essage that is passed fro$ node to node, there are additional ob6ects that serve as conte4tual infor$ation at different states pecifically we have-

•

conte4t

•

flow

•

global

!e can install ode)"E with$ sudo &pm i&stall -g &ode-red

(his co$$and can take so$e ti$e to run and will download a lot of prere/s nce installed, we can start it fro$ the co$$and line with$ &ode-red Page 12,

(he server now listens on port 1GG0 for inco$ing traffic In addition to running ode)"E standalone, ode)"E can be e$bedded into your own ode6s application ee also•

ode)"E ho$e page

•

ode)"E Progra$$ing Auide

•

Nou(ube- HIP (utorials- Installing ode)"E

2ode-ED )*+P local installation !e can install ode)"E with$

&pm i&stall &ode-red

(his will install a copy of ode)"E relative to your current director y n $y HIP, this tool about @ $inutes to install Fro$ there, we can navigate to 5&ode7modules&ode-red

In there we will find an e4ecutable called *red6s* If we run that progra$ with * &ode red5Is* we will start ode)"E and we should see $essages si$ilar to the following'elcome to >ode-(E? 9999999999999999999 ! ! ! ! ! ! ! ! ! ! ! ! ! !

+ug +ug +ug +ug +ug +ug +ug +ug +ug +ug +ug +ug +ug +ug

233140 233140 233140 233140 2331!3 2331!3 2331!3 2331!3 2331!3 2331!3 2331!3 2331!3 2331!3 2331!3

-

Si&foT Si&foT Si&foT Si&foT S%ar&T S%ar&T S%ar&T Si&foT Si&foT Si&foT Si&foT Si&foT Si&foT Si&foT

>ode-(E? /ersio& /05145H >ode5Is /ersio& /45456 Ai&ux 454511-&tc arm AE Aoadi&g palette &odes -----------------------------------------------------Srpi-gpioT =&fo  =g&ori&g (aspberr, Pi specific &ode -----------------------------------------------------)etti&gs file  omecip5&ode-redsetti&gs5Is 8ser director,  omecip5&ode-red lo%s file  omecip5&ode-redflo%s7cip25Iso& :reati&g &e% flo% file )tarti&g flo%s )tarted flo%s )er/er &o% ru&&i&g at ttp1265050511GG0

!e can now start a browser and point it to port 1BB0 on the HIP Personally, I like to use a browser on $y desktop P 6ust for speed and convenience

2ode-ED indows installation ode)"E can be installed on Microsoft !indows First we download and install the latest ode6s runti$e !hen started, the following screens are shown-

First there is a welco$e screen-

Page 12<

e4t, the obligatory license agree$ent-

ow we get to supply the directory into which ode6s will be installed-

Page 129

ow we get to select the options we wish to include-

(his is the last chance to stop before the install is perfor$ed-

Page 1/0

 #nd now ode6s is installed-

 #fter installation we can bring up a co$$and windows and validate that the installation succeeded-

Page 1/1

!ith ode6s installed, we can now e4ecute the co$$and to install ode)"E:J &pm i&stall -g &ode-red

nce installed, we can run it with the co$$and * &ode-red* (he result will be the console log as follows-

(o connect to ode)"E, it is business as usual withhttp-..localhost-1BB0. n !indows, your local ode)"E user directory is:^8sers^8ser>ameJ^5&ode-red

ee also•

Page 1/2

ode)"E installation

2ode-ED – writing flows !hen we author a flow we do so in the browser n the left of the screen are a series of categories within which node types $ay be found (hese $ay be dragged and dropped onto the drawing canvas Fro$ there, the output of one node $ay be linked to the input of another !hen a flow diagra$ has been changed but not yet deployed, the nodes that are different fro$ the deployed versions have a blue circle to show that they are as yet un) deployed For e4a$ple the blue circle here indicates it is un)deployed

Following deploy$ent, the sa$e node changes its appearance to-

 #fter we have written a flow we can e4port that flow for distribution to others Fro$ the $enu at the top right, we can select * Export J :lipboard* which will open up a dialog fro$ which the ? describing the flow can be copied

!e can rena$e a flow by double clicking on its header in the editor panel !hen we wire one node to another, we are e4plicitly passing data in the for$ of a $essage between the nodes ince the flow e4ecutes in one direction, we can use the phrase *upstrea$* to $ean nodes e4ecuted earlier in the flow that others which are *downstrea$* Page 1//

(he $essage passed between the nodes is a ?avacript ob6ect +y convention, we co$$only use a property of that ob6ect called * pa,load* to identify the content !hen a flow is started, it is always a new $essage that flows downstrea$ If we need to $anage state across flow instances we can do that too (here is a variable called *co&text* that $aintains data specifically for that instance of the node !e can invoke it with *co&text5get.&ameJ* and *co&text5set.&ameJ /alueJ*  # second level of state data is the *flo%* ob6ect (his is a data ob6ect that is available to all instance of nodes within a given flow #gain we can access it with * flo%5get.&ameJ* and *flo%5set.&ameJ /alueJ* Finally there is state data that is available to all nodes in all flows across the environ$ent (his is accessed through the * global* ob6ect with * global5get.&ameJ* and *global5set.&ameJ /alueJ* !e can log debug $essages with the functions &ode5log.textJ, &ode5%ar&.textJ and &ode5error.textJ (o throw an error, we should call &ode5error.textJ messageJ ee also•

rror- "eference source not found

•

ode)"E docu$entation L !riting Functions

(dvanced 2ode-ED configuration !hen you run ode)"E, a configuration file is deposited in $;DE5&oderedsetti&gs5Is (his file contains a ?avacript ob6ect that is read and contains configuration details-

•

flowFile L (he file na$e used to store the flows (his defaults to *flo%s7ost&ameJ5Iso&*

•

uiPort L (he (P.IP port nu$ber that a browser will use to connect (he default is 1BB0

•

editor*eme L tyling for the 7I

•

mUtt(eco&&ect*ime L For MU(( nodes, if the connection to the MU(( broker is lost, how long in $illiseconds should we wait until we atte$pt to re)establish the connection (he default is 2000 82 seconds9

•

serial"econnect(i$e L For serial nodes, if we lose connection to the serial port, how long in $illiseconds should we wait until we atte$pt to re)open the port (he default is 2000 82 seconds9

•

debugaxAe> L Ma4i$u$ length of a debug line before it is truncated (he default is 1000 characters

Page 1/

•

fu&ctio&
•

loggi&g L ontrols for logging ◦ le/el L (he debug output level ◦ $etrics ) ◦ audit )

ee also•

ode)"E onfiguration

+ncluding additional npm packages :et us assu$e that you want to use function that is available to node6s as an PM package How can we do that (he answer is to $odify the setti&gs5Is file that, by default, can be found in the $;DE5&ode-red directory !ithin that file, look for the entry called *fu&ctio&
then at run)ti$e, you will be able to code global5get."x,C" in your function nodes It is also i$portant to install the underlying packages that you want to use (hese should be added to the &ode7modules directory in $;DE5&ode-red For e4a$ple, if you want to use package @LO, then you should change to $;DE5&ode-red and then use np$ to install @LO relative to there !e will then find the @LO package in the relative &ode7modules directory

riting )ustom 2ode-ED nodes  #lthough the set of ode)"E nodes is rich and there are $any contributed additional nodes available, there are ti$es when you $ight need so$e speciali%ed node i$ple$entation ode)"E provides the ability for you to create your own custo$ nodes

 # custo$ node is i$ple$ented pri$arily is two files ne is a ?avacript file that provides its core run)ti$e behavior and the other is an H(M: file that describes how it will appear in the editor with dialogs  #t a high level, the i$ple$entation of the ?avacript source should bemodule5exports 9 fu&ctio&.(E?  fu&ctio& &ode>ameJ>ode.co&fig  (E?5&odes5create>ode.tis co&figY /ar &ode 9 tisY tis5o&.Wi&putW fu&ctio&.msg  Page 1/$

 do someti&g &ode5se&d.msgY

  

 (E?5&odes5register*,pe."&ode>ameJ" &ode>ameJ>odeY 

(o understand this, we find that there is a function called &ode>ameJ>ode that is registered to be invoked when ever a new instance of the node is created (his function is passed an ob6ect that contains the node specific properties that were set by the user in the editor !hen a node is reached in a flow, it receives an inco$ing event called * i&put* (he *co&fig* para$eter is passed in for each instance of the node It contains both the properties defined specifically for that node as well as so$e other syste$ properties (he syste$ properties include-

•

id L # uni/ue IE for this node in the flow

•

t,pe L (he type of node that this represents 8a string9

•

C L 7nknown

•

x L J location in the canvas

•

, L N location in the canvas

•

%ires L #n array of wires &

(he H(M: for a new custo$ node defines a nu$ber of ite$s First there is a script that is run that initiali%es the node (his has a fi4ed for$ and looks likescript t,pe9"textIa/ascript"J (E?5&odes5register*,pe."&ode>ameJ"  categor, _ color _ defaults   i&puts 1 outputs 1 ico& "image file &ameJ" label fu&ctio&.  retur& "label stri&gJ"Y  Y scriptJ

In addition to the script, we can provide co$ponents for the configuration and for the help (he configuration is for$atted asscript t,pe9"textx-red" data-template-&ame9"&ode>ame"J di/ class9"form-ro%"J  Dter ;*A   di/J scriptJ

(he H(M: that we in6ect on a per configuration option basis is of the for$Page 1/)

di/ class9"form-ro%"J  ;*A ere di/J

!e want the row to start with a label that describes what the option (his is added withlabel for9"idJ"J _ labelJ

It is co$$on to place an icon at the start usingi class9"fa ico&>ameJ"JiJ

(hese are Font #weso$e font na$es Following the label will be the i&putJ tag that is used to pro$pt the user for the value of the option It must have an id value of * &odei&put-optio&>ameJ* Here are so$e e4a$plesFor a si$ple te4t inputi&put t,pe9"text" id9"&ode-i&put-database" placeolder9"database"J

For a selectionselect t,pe9"text" id9"&ode-i&put-operatio&"J optio& /alue9"i&sert"Ji&sertoptio&J optio& /alue9"delete"Jremo/eoptio&J selectJ

!ithin the ode)"E browser environ$ent, we should assu$e the e4istence of 6Uuery (his $eans that we can also include 6Uuery ?avacript !e can use this to update the page as a function of what has been changed For e4a$ple, the following shows a selection that shows or hides options as a function of what is selected-

   

 

   

       

di/ class9"form-ro%"J label for9"&ode-i&put-retrie/al*,pe"Ji class9"ico&-tasks"JiJ *,pelabelJ select t,pe9"text" id9"&ode-i&put-retrie/al*,pe"J optio& /alue9"b,=d"J555 b, =doptio&J optio& /alue9"b,ie%"J555 b, ie%optio&J selectJ di/J di/ class9"form-ro% &ode-i&put-desig&?oc"J label for9"&ode-i&put-desig&?oc"Ji class9"ico&-tasks"JiJ ?esig& doclabelJ i&put t,pe9"text" id9"&ode-i&put-desig&?oc" placeolder9"?esig& doc"J di/J di/ class9"form-ro% &ode-i&put-/ie%>ame"J label for9"&ode-i&put-/ie%>ame"Ji class9"ico&-tasks"JiJ ie% &amelabelJ i&put t,pe9"text" id9"&ode-i&put-/ie%>ame" placeolder9"ie% &ame"J di/J scriptJ $."F&ode-i&put-retrie/al*,pe"5ca&ge.fu&ctio&.  /ar t,pe 9 $."F&ode-i&put-retrie/al*,pe"5/al.Y if .t,pe 99 "b,=d"  $."5&ode-i&put-desig&?oc"5ide.Y $."5&ode-i&put-/ie%>ame"5ide.Y  else  $."5&ode-i&put-desig&?oc"5so%.Y $."5&ode-i&put-/ie%>ame"5so%.Y  Y

Page 1/,

For the help, the for$at isscript t,pe9"textx-red" data-elp-&ame9"&ode>ame"J pJ;elp textpJ scriptJ

ee also•

ode)"E L reating odes

2ode definition properties !hen we register a node type using the (E?5&odes5register*,pe. $ethod, this can accept an ob6ect which contains the configuration properties for the new node (hese properties are well docu$ented in the on)line web pages # su$$ary follows-

•

categor, L (he category in the palette in which this node will appear (he following shows so$e of the e4isting categories-

•

defaults L Eefinitions for each of the editable.custo$i%able properties for the node !e create an ob6ect called defaults and for each new property to be e4posed fro$ the node, we create a property as an i$$ediate child of defaults (he value of that property will itself be an ob6ect with a property called value that will contain the default value For e4a$ple, if we wanted our node to e4pose an editable property called *street* we would define-

defaults  Page 1/<

street  /alue "default streetJ"  

(he properties of the node e4posed property can be-

◦ /alue L (he default value ◦ reUuired L !hether or not this is a re/uired property ◦ /alidate L # function used to validate the property ◦ t,pe L  •

crede&tials L redentials which are stored separately fro$ the node and hence not e4ported when the flow is e4ported

•

i&puts L (he nu$ber of inputs to this node (he values that are allowed are 0 or 1

•

outputs L (he nu$ber of outputs fro$ this node Dalues can be 0 or $ore

•

ico& L (he identity of the icon to use in the node ither ode)"E supplied icons or custo$ icons $ay be used (he icon should be a PA with a transparent background with white pi4els and be 0430 pi4els in si%e

•

color L (he background color of the node (his is typically supplied as a he4 "A+ value # set of suggested colors are declared so that we can have so$e for$ of consistency in our nodes (hese are docu$ented here

•

label L (he label to use on the node

•

paletteAabel L (he label to show on the palette

•

label)t,le L (he style of the label

•

alig& L How the icon and label will be aligned on the node (he default is left)aligned but we can supply the value * rigt* for right align$ent

+nstalling )ustom 2ode-ED modules during development n a !indows syste$, we will find a directory called:^8sers^user>ameJ^5&ode-red^&ode-modules

In there will be a directory for each $odule that is in addition to the default $odules supplied with the ode)"E package For e4a$ple, if we wish to add a node called *,>ode*, we would create a directory called:^8sers^user>ameJ^5&ode-red^&ode-modules^,>ode

ontained within will be the content of the custo$ node

Page 1/9

haring 2ode-ED flows (he flows created within ode)"E can be e4ported as ? docu$ents and shared.given to others as this te4tual representation

GP+O with 2ode-ED ince ?ohnny)Five is the defacto standard for API in ?avacript and ode)"E is all about ?avacript, the ?ohnny)Five plugin for ode)"E is e4actly what we need ince it does not co$e pre)supplied with ode)"E, we $ust $anually install it pecifically, the following np$ packages $ust be installed-

•

&ode-red-co&trib-gpio L +inding between ode)"E and 6ohnny)five

•

Io&&,-fi/e L 6ohnny)five itself 

•

cip-io L I $odule for 6ohnny)five bindings for HIP

In the ho$e directory for ode)"E, run$ &pm i&stall &ode-red-co&trib-gpio Io&&,-fi/e cip-io

"unning this installation on $y HIP took about 10 $inutes nce done an ode)"E restarted, we will find that we have so$e new nodes in our palette pecifically, we will findThis node is called to delier a signal to an out!ut *PI3.

This node is drien "hen a signal changes on an in!ut *PI3.

Initiali;e soe Aohnny-ie library and ake that unction aailable to the rest o the lo".

(he gpio input and output nodes are pretty straightforward, however, the *6ohnny2* node needs a little $ore e4planation (his node hosts so$e ?avacript that is e4ecuted  when the flow is deployed or ode)"E is started and the ?ohnny)Five o&(ead,. callback is fired #t this ti$e, we can register any ?ohnny)Five setup functions with callbacks If a ?ohnny)Five callback fires, it can then fire a $essage out of the *6ohnny2* node output ter$inal causing a new flow instance to run Fro$ here, we can run&ode5se&d.topic "someti&g" pa,load "someti&gelse"Y

ee also•

np$ L node)red)contrib)gpio

•

np$ L chip)io

•

?ohnny)Five

Page 10

%ecurity %ecurity and userids !hen you login to :inu4, you login with a userid (he default is the user * cip* with password *cip* (his is an *ordinary* userid and not the sa$e as root or superuser ne can always switch to that user but then all co$$ands e4ecuted are perfor$ed as root and if a typing $istake is $ade, you can literally ruin your environ$ent # solution to the proble$ is to use the *sudo* co$$and udo takes as a para$eter the na$e and para$eters of another co$$and udo then switches to root, and then runs that co$$and as root However, when the co$$and co$pletes, the switch to root is not $aintained (hus, in effect, we run as root for 6ust the duration of the co$$and ne of the pri$ary configuration files for sudo is etcsudoers (his contains the rules that govern which users $ay e4ecute sudo and for what co$$ands n the HIP, the userid called *cip* is fully authori%ed to run any co$$and and does not have to provide any passwords !ithin that file we will find a rich set of options (he one of interest to us readssudo +AA9.+AA+AA +AA

which says that any user that is in the group *sudo* 8which chip is9 can run any co$$and as root (his is great  but we are pro$pted for a validation password If we want to avoid being asked for a password, we can change the line to readsudo +AA9.+AA+AA >DP+))'?+AA

ee also•

$an8B9 L sudo

•

sudo Ho$e Page

udio HIP is capable of generating an audio output signal (here are a nu$ber of possible output destinations (he first is to carry the audio signal as part of the co$posite output # second solution is to plug in a set of audio speakers using the sa$e 6ack (here are a nu$ber of tools available to play audio (ools-

•

apla, L Play a PM sound fro$ a file o$e of the $ore i$portant flags are◦ -l L list devices ◦ -A L list PMs ◦ -?9>+E L select device

Page 11

•

arecord L "ecord an audio input strea$ ote that aplay and arecord are basically the sa$e application

•

alsactl

•

speaker-test L Play tones and other sounds to test the speaker o$e of the $ore i$portant flags are-

◦ -? >+E L select device ◦ -t pi&k|si&e|%a/ L (he type of output to produce ◦ -f freU L fre/uency of sine wave in HG •

alsamixer L a full screen 8te4t9 audio $i4er 

•

amixer L a co$$and line audio $i4er 

•

mpg123 L MP3 player 

ne of the easiest ways to play audio fro$ within your application is to spawn a sub)process such as apla, or mpg123 using a syste$ call

U%B attachable audio  # neat little gi%$o is the 7+ attachable audio devices (hese are adapters that plug into a free 7+ slot and e4pose a line out and possibly a $icrophone input #n e4a$ple of this is abrent 7+)+D sound card !hen plugged in, it shows as a 7+ device that lists asBus 001 ?e/ice 041 =? 0dGc000e :-edia Electro&ics =&c5 +udio +dapter .Pla&et 8P-100
(o play audio through this device re/uires us to specify it as the hardware output For e4a$ple$ mpg123 -o alsa -a plug%10 example5mp3

 #nother popular device is based on the M10B chip set Eevices based on this architecture can be found on e+ay for about ;120 (hese cards show up asBus 001 ?e/ice 004 =? 0dGc013c :-edia Electro&ics =&c5 :10G +udio :o&troller

If you are attaching a $icrophone for audio input, e4a$ine carefully the plug (he plug needs to $atch the input specs of the adapter pecifically, there are two pri$ary styles of plug Page 12

(hese are (ip "ing leeve 8("9 and (ip "ing "ing leeve 8(""9 For these cheap devices, the $icrophone input is al$ost invariably (ip "ing leeve style

(inu) (% – d'anced (inu) %ound rchitecture (o deter$ine what sound cards are available, we can e4a$ine the procasou&dcards file #n e4a$ple output $ight be0 Ssu&4icodec   1 S?e/ice

T su&4i-codec  su&4i-codec su&4i-codec T 8)B-+udio - 8)B P&P )ou&d ?e/ice :-edia Electro&ics =&c5 8)B P&P )ou&d ?e/ice at usb-1c144005usb-1

full speed

(o progra$ against #:#, we need to install the develop$ent environ$ent found in the libasou&d2-de/ package $ sudo apt-get i&stall libasou&d2-de/

ee also•

Introduction to ound Progra$$ing with #:#

•

Progra$$ing L(utorial- #:# (utorial 1 L Initiali%ation

•

 # close look at #:#

Pulse )ode #odulation (o properly understand audio on the Pi, we $ust understand how audio signals can be encoded

First we discuss the concept of sa$pling a$pling is the act of e4a$ining the original audio signal at regular sa$ple intervals How $any sa$ples (he answer is lots and lots of sa$ples I$agine a s$all section of 1 second of sound If we sa$ple every 1.10th of a second, that would give us 10 sa$ples (ypically, we sa$ple at far higher rates such as C0,000 sa$ples per second (he $ore sa$ples we take, the closer to the original source signal we will have captured (he $ore sa$ples we take, the larger our data will be for a given period of ti$e For e4a$ple, if we sa$pled 10 ti$es per second, we would have only 10 data points to $anage If we sa$ple C0,000 sa$ples per second, we have C0,000 data points to $anage #s you can see the $ore sa$pling we do, the $ore data we are forced to $anipulate (he trade off is that the $ore sa$ples one takes, the higher the *fidelity* to the original source signal !hen we do so$e nu$ber of repeated things per second, we have a unit of $easure$ent for  e4pressing this M it is called the hert% If we have 1 hert%, then we are doing 1 thing per second If we have C0,000 hert%, then we are doing C0,000 things per second (hinking along these lines, we can e4press our sa$ples in hert% If I a$ sa$pling at C05H%, then I a$ taking C0,000 sa$ples per second (his is e/uivalent to saying I a$ taking one sa$ple every 1.C0000th of a second Page 1/

(he ne4t thing we need to consider is what does an individual sa$ple consist of In audio, it is the a$plitude of the signal (his is an analog value (here could be co$plete silence 809 or $a4i$u$ volu$e that we could sense 819 or a value #N!H" in between (o encode an analog value in a co$puter can take a lot of $e$ory # typical floating point nu$ber $ight be B or 1@ bytes ur reality is that we don't usually need this level of granularity Instead what we can do is perfor$ a step known as */uanti%ation* i$ply put, this is the $apping fro$ an analog data point to one of a $uch s$aller set of discrete possibilities I$agine a co$puter byte (his is an B bit value that can range fro$ 0 to 22 ow i$agine we $ap the analog values in the range of 0J1 to the < bit alues o 0J2$$. +o 0J0 and 1J2$$ M and the other alues "ould a! !ro!ortionally. -or ea!le4 an analog alue o 0.$ "ould a! to 12<. The result o this uanti;ation is that "e lose inoration in echange or co!actness. -or ea!le4 0.9994 0.99<4 0.99, "ould all a! to 2$$ M and i all "e hae is the nuber 2$$4 "e no longer kno" "hich o the !ossible analog alues "as the real alue that "e encoded into. Ho"eer4 i "e diide 1F2$$ "e get 0.00 so our encoded alue "ill be !retty darn close. 3 course4 "e are not liited to encoding our analog alue in only < bits4 "e could certainly use ore bits ?or ea!le 2 bytes N 1) bits@ to achiee higher idelity. Putting these conce!ts together4 our encoding schee is to sa!le a alue any ties !er second and or each alue4 uanti;e it by a!!ing it to the a!!ro!riate binary alue. This strea o bytes then becoes the encoding o our original audio signal. +ee alsoK

•

Music and o$puters

(1( programming (he #:# progra$$ing $odel is a  language library that can be linked in with your own applications (he device drivers for driving the hardware are provided by the #:# i$ple$entation and our concerns beco$e pri$arily those focused on driving the higher level logic (he high level library is called libasou&d #:# itself is co$posed of a nu$ber of $a6or interfaces (hese include-

•

ontrol interface

•

PM interface

•

MIEI interface

•

Mi4er interface

:ogically, think of #:# as the driver for the sound syste$ ince audio signal input and output is best perfor$ed by hardware devices as opposed to the P7, we are pri$arily concerned with driving these devices ince a Pi can have $ultiple audio devices attached to it, we need a $echanis$ of specifying which device we want to interact with #:# allows us to identify devices by na$e If we run the *apla, -A* co$$and, we will be rewarded with a list of #:# addressable devices For e4a$ple&ull ?iscard all samples .pla,back or ge&erate Cero samples .capture default dsp0 dmixer s,sdefault:+(?9su&4icodec   su&4i-codec

Page 1

?efault +udio ?e/ice dmix:+(?9su&4icodec?E90   su&4i-codec ?irect sample mixi&g de/ice ds&oop:+(?9su&4icodec?E90   su&4i-codec ?irect sample s&oopi&g de/ice %:+(?9su&4icodec?E90   su&4i-codec ?irect ard%are de/ice %itout a&, co&/ersio&s plug%:+(?9su&4icodec?E90   su&4i-codec ;ard%are de/ice %it all soft%are co&/ersio&s

If we plug in a 7+ based sound card, even $ore options beco$e availabledefault:+(?9?e/ice
(he identity of a device is co$$only na$ed *%:+(?9:ard>ame?E9?e/ice>umber* ne of the i$portant considerations for audio input and output is the si%e of the data If we think of a channel of audio output, it is likely to be a fre/uency of CC5H% and 1@bits 8 bytes9 a sa$ple (his is BB5bytes a second Me$ory $anage$ent is a big consideration in #:# progra$$ing (he $e$ory $anaged by #:# is based on a buffer which is subdivided into units called periods where each period consists of fra$es where a fra$e contains channels  #t a high level, a typical audio output application will have the following general algorith$Dpe& te output de/iceY Page 1$

Prepare te de/ice for outputY 'ile tere is data to be pla,ed  %rite P: data to te output de/iceY 

(o write a  progra$ that works with #:#, we start by including the header file called *alsaasou&dlib5J* (his provides the signatures and constants for our code ur progra$ will begin by opening the device !e use the s&d7pcm7ope&. call for this task For e4a$ples&d7pcm7t Ra&dleY rc 9 s&d7pcm7ope&.a&dle "de/ice>ameJ" )>?7P:7)*(E+7PA+LB+:N 0Y

 # return code of less than %ero indicates an error e4t we setup so$e hardware para$eterss&d7pcm7%7params7t RparamsY s&d7pcm7%7params7alloca.paramsY s&d7pcm7%7params7a&,.a&dle paramsY

(he hardware para$eters infor$ the drivers of so$e of the core data ite$s we are going to use including-

•

data for$at 8eg ETPMTF"M#(T1@T:9

•

nu$ber of channels 81 or 9

•

sa$pling rate 8eg CC1009

nce we have populated our hardware para$eters structure, we can then write those new para$eters to the driver with s&d7pcm7%7params. ee also•

 #:# pro6ect L the  library reference

•

Introduction to ound Progra$$ing with #:#

,-#, de"ice enumeration

If we need to deter$ine what devices are available on our $achine, we can ask #:# for such a su$$ary !e do this by creating a cursor like interface First we call s&d7de/ice7&ame7i&t. asking for an iterable list of devices (hen we walk through the list 8while the current ele$ent is not 7::9 and ask for the details of that device #t the end, we release the storage for the list (his is shown in the following sa$ple/oid alsa7list=&put?e/ices.  i&t rcY /oid RRi&tsY rc 9 s&d7de/ice7&ame7i&t.-1 "pcm" i&tsY if .rc K9 0    retur&Y  i&t i 9 0Y %ile.i&tsSiT K9 >8AA  car R&ame 9 s&d7de/ice7&ame7get7i&t.i&tsSiT ">+E"Y car Rdesc 9 s&d7de/ice7&ame7get7i&t.i&tsSiT "?E):"Y car R=D=? 9 s&d7de/ice7&ame7get7i&t.i&tsSiT "=D=?"Y if .=D=? 99 >8AA || .=D=? K9 >8AA  strcmp.=D=? "=&put"990  pri&tf."?e/ice >ame9s^& -- ?escriptio&9s^&" &ame descY

Page 1)

       

 if .&ame  free.&ameY  if .desc  free.descY  if .=D=?  free.=D=?Y  i]]Y

   s&d7de/ice7&ame7free7i&t.i&tsY   E&d of list?e/ices

,-#, audio input  capture

 #udio output is /uite straight forward, but what about audio input If we attach a $icrophone or audio strea$ to an #:# input source, we should be able to encode the resulting data !e start by e4ecuting a call to s&d7pcm7ope&. passing in the $ode type of )>?7P:7)*(E+7:+P*8(E #gain, we allocate the hardware para$eter block and then set the characteristics of how we want the audio to be presented M for e4a$ple-

•

access L ETPMT#T"!TI(":#DE

•

ca&&els L 1

•

rate L CC1kHG

•

period L 3 fra$es

!hen done, we can start reading data using s&d7pcm7readi. (he result will be data read into our buffers

,-#, from !a"a#cript

!hen working with audio data, we typically think of high speed processing with large volu$es of data and hence we need to be as efficient as possible In a :inu4 environ$ent, $a4i$u$ efficiency is usually achieved through  language progra$$ing +ut what of our friend ?avacript an we process audio data in that language using ode6s  # package for working with certain aspects of #:# can be found on np$ with the package being called *alsa*

&re8uency %pectrum naly7er  !e have all seen those pleasing :E or :E graphs that show the audio playing on your stereo as a se/uence of bars

Page 1,

!hat these graphs are showing is the fre/uency content in an audio signal (hink of an audio signal like a bea$ of white light ?ust like light can be deco$posed into the su$ of light waves at different fre/uencies, so too can an audio signal !hat we hear is a co$bination of partial sounds at different fre/uencies that when co$bined are the totality of what we perceive Aiven an input audio signal, we can deco$pose it into its constituent parts Fro$ there, we can choose to graph it out If the input source is changing 8such as playing $usic9 then we can translate the a$ounts of different fre/uencies into other perceptions such as light intensity or color changes (he key to breaking down the audio into its co$ponent parts is the $athe$atics of the Fourier (ransfor$ (hat is $uch $ore $ath than we will need to co$prehend 8nor do I understand or could possibly e4plain M nor would want to try and e4plain to you9 However that doesn't stop us fro$ using the techni/ue (he algorith$ we will use is called a Fast Fourier (ransfor$ 8FF(9 It takes as input a sa$ple of data 8ideally a power of  in si%e9 and returns us an array of Fourier coefficients Its okay, there is not any real need to know what that $eans ach $e$ber of the array is a $athe$atical co$ple4 nu$ber (his $eans it has a real part and in i$aginary part Aenerically, a co$ple4 nu$ber is represented asa + bi

where *a* is the real part and * b* is the co$ple4 part 8 LiL is the iaginary nuber@.

8et us iagine "e

hae = sa!les then our array ro the --T "ill beK a0Ob0i

a1Ob1i

a2Ob2i

...

a =1Ob =1i

The alue "e "ant instead o co!le nubers is the agnitude o the co!le nuber "hich is gien byK 2

2

( a +b ) :et us represent the $agnitude as M ow we have an array of $agnitudes:0

:1

:02

...

: =1

ach ele$ent in the array will now represent the a$ount of a specific fre/uency (he > values will be an e/ually spaced distribution of the input fre/uency For e4a$ple, if we have captured audio at a $a4 rate of CC100 sa$ples.second 8CC15H%9, then the each ele$ent in the array will span 4451N;C> For e4a$ple, if we are working on a sa$ple si%e of 10C ele$ents, each ele$ent in the array will contain the a$ount of fre/uency in 8appro4i$ately9 C3H% chunks (here is a little $ore to consider In an FF( result, only  the resulting data is of use to us If we have an output of > results, we only care about the first >2 values

Page 1<

ne of the pri$ary i$ple$entations of FF( is called FF(! (his can be installed on a Pi fro$ the package *libfft%3-de/* $ sudo apt-get i&stal libfft%3-de/

ee also•

FF(!

•

How to e4tract fre/uency infor$ation fro$ sa$ples fro$ Port#udio using FF(! in 

•

How to generate the audio spectru$ using fft in KK

•

 #naly%e audio using Fast Fourier (ransfor$

•

ine tone generator 

The libsndfile library ound files are encoded in a nu$ber of distinct for$ats In order to read and write fro$ these files, one $ust study the for$ats and write suitable parsers and constructors Fortunately, a library called *libs&dfile* has already been created for 6ust that purpose and si$plifies our  work (his package is available via apt)get First there is libsndfile1 which contains 6ust the libraries and then there is libs&dfile1-de/ which contains the libraries and the header files necessary for building your own apps sudo apt-get i&stall libs&dfile1 libs&dfile1-de/

(o build an application one should include * s&dfile5J* and link with * -ls&dfile* otes-

•

(he #PI is well docu$ent and pretty straightforward

•

(ake care with sf7cou&t7t It is an int@C and when used with pri&tf. for$ats needs to be cast to an int or used with the for$at specifier of * lld*

Here is a sa$ple application that lists the headers and reads so$e dataFi&clude Fi&clude Fi&clude Fi&clude

stdio5J s&dfile5J stri&g5J stdlib5J

i&t mai&.i&t argc car RRarg/ST  )7=>D i&foY )>?=AE RfileY if .argc K9 2  pri&tf."8sage s file>ame^&" arg/S0TY retur& -1Y  memset.i&fo 0 siCeof.i&foY file 9 sf7ope&..co&st car Rarg/S1T )7(E+? i&foY if .file 99 >8AA  pri&tf."Error s^&" sf7strerror.fileY retur& -1Y  pri&tf."'orki&g of file s^&" arg/S1TY pri&tf." - frames d^&" i&fo5framesY pri&tf." - samplerate d^&" i&fo5samplerateY

Page 19

     

     

         

pri&tf." - ca&&els d^&" i&fo5ca&&elsY pri&tf." - format x^&" i&fo5formatY s%itc.i&fo5format  )7D(+*7*LPE+)N  case )7D(+*7'+ pri&tf." - '+^&"Y breakY default pri&tf." - 8&k&o%& format^&"Y breakY  s%itc.i&fo5format  )7D(+*7)8B+)N  case )7D(+*7P:7)G pri&tf." - )ig&ed G bit^&"Y breakY case )7D(+*7P:71H pri&tf." - )ig&ed 1H bit^&"Y breakY default  pri&tf." - 8&k&o%& sub-format^&"Y breakY   s%itc.i&fo5format  )7D(+*7E>?+)N  case )7E>?=+>7=AE pri&tf." - ?efault file e&dia&^&"Y breakY case )7E>?=+>7A=**AE pri&tf." - Aittle e&dia&^&"Y breakY case )7E>?=+>7B=< pri&tf." - Big e&dia&^&"Y breakY default pri&tf." - 8&k&o%& e&dia&^&"Y breakY  pri&tf." - sectio&s d^&" i&fo5sectio&sY pri&tf." - seekable d^&" i&fo5seekableY i&t items 9 1024Y sort Rbuffer 9 .sort Rmalloc.siCeof.sort R items R 2Y if .buffer 99 0  pri&tf."Error ailed to allocate storage^&"Y retur& -1Y  sf7cou&t7t cou&tY cou&t 9 sf7read7sort.file buffer itemsR2Y pri&tf."(ead d items^&" .i&tcou&tY if .cou&t 99 0  pri&tf."Error s^&" sf7strerror.fileY 

    

sf7close.fileY free.bufferY

For writing an output !#D file, here is so$e $ore sa$ple codeFi&clude stdio5J Fi&clude s&dfile5J Fi&clude "sou&d8tils5" static )>?=AE Rsou&dileY /oid sou&dile7start)a/e.car Rfile>ame i&t frames  )7=>D sfi&foY sfi&fo5samplerate 9 44100Y sfi&fo5ca&&els 9 1Y sfi&fo5format 9 )7D(+*7'+ | )7D(+*7P:71H | )7E>?=+>7=AEY i&t mode 9 )7'(=*EY sou&dile 9 sf7ope&.file>ame mode sfi&foY if .sou&dile 99 >8AA  pri&tf."Error s^&" sf7strerror.sou&dileY  

Page 1$0

/oid sou&dile7%rite?ata.sort Rdata i&t items  sf7%rite7sort.sou&dile data itemsY  /oid sou&dile7e&d)a/e.    sf7%rite7s,&c.sou&dileY   sf7close.sou&dileY 

ee also•

libsndfile

•

Aithub- erikd.libsndfile

•

libsndfile api

%peech output (here is a software package called * e)peak* that can be installed by$ sudo apt-get i&stall espeak

(o speak a phrase we can enter$ espeak "*is is a test" --stdout | apla,

(o si$ply speak phrases, run espeak by itself ach line entered followed by return speaks the result (he software can include languages "un$ espeak --/oices

to see a list of the available voices (o supply a different voice use the *-/ /oiceJ* co$$and For e4a$ple$ espeak -/ e&-sc "= ca& speak %it a )cottis acce&t5" --stdout | apla,

 #nother te4t to speech tool is called *festival* that can be installed by$ sudo apt-get i&stall festi/al

(o $ake it speak, we can then pipe te4t into, for e4a$ple$ eco "*is is a test" | festi/al --tts

ee also•

epeak te4t to speech

•

Festival.festvo4 downloads

•

Festival $anual

(ogging Messages fro$ various syste$s and subsyste$s are logged into files in the /arlog directory (here are $any log files fro$ all different types of sources here o$e of the $ore i$portant arePage 1$1

•

ker&5log L (he kernel $essages log

•

user5log L 7ser application $essages

•

aut5log L #uthori%ation $essages

•

daemo&5log L Eae$on $essages

•

ker&5log L 5ernel $essages

(he dmesg co$$and displays the kernel logs fro$ a $e$ory ring buffer 8a $e$ory buffer that loops around on itself9 ow let us look and see how logging is actually i$ple$ented on HIP It is based on the rs,slogd de$on It is started by default and we can validate that it is running with$ s,stemctl status rs,slog X rs,slog5ser/ice - ),stem Aoggi&g )er/ice Aoaded loaded .libs,stemds,stemrs,slog5ser/iceY e&abled +cti/e acti/e .ru&&i&g si&ce *u 201!-12-31 1!361H :)*Y 1 da, 3 ago ?ocs ma&rs,slogd.G   ttp%%%5rs,slog5comdoc  ai& P=? 4G# .rs,slogd :
(he configuration file for rsyslogd can be found at etcrs,slog5co&f (his is a rich file and I don't reco$$end editing it without first studying in detail the docu$entation on rs,slogd (he high level notion is that when a $essage is generated, it is generated by a particular *type* of application (he rs,slogd calls this a *facility* In addition, when a $essage is issued it is issued for a reason bviously the reason is to log so$ething for future e4a$ination but here we take the reason to $ean why the $essage was issued For e4a$ple, is it a warning Is it debug (he rs,slogd calls this the *severity* of the $essage ow we have a richer conte4t for considering a $essage !hen a $essage is issued it contains within both the facility and severity (he configuration of rs,slogd can then use this additional $eta infor$ation to route the $essage to the appropriate destination (o log a $essage, we use the s,slog function !e $ust also include s,slog5 (he signature of s,slog is/oid s,slog.i&t priorit, co&st car Rformat _

(he priorit, is the encoding of both the facility and severity (he format para$eter is a pri&tf. style for$at string with optional para$eters following (here are definitions provided for the facility-

•

AD<7+8*; L #uthori%ation $essages

•

AD<7+8*;P(= L Private authori%ation $essages

•

AD<7:(D> L Messages related to the cron dae$on

•

AD<7?+ED> L Messages related to dae$on processes

Page 1$2

•

AD<7*P L Messages related to file transfer through F(P

•

AD<7NE(> L Messages fro$ the kernel

•

AD<7AD:+A0 L AD<7AD:+A6 L Messages sources for local use

•

AD<7AP( L Messages related to interaction with printers

•

AD<7+=A L Messages related to the receipt or delivery of $ail

•

AD<7>E') L Messages related to the 7senet news subsyste$

•

AD<78)E( L Aeneric $essages

•

AD<788:P L Messages related to the 7ni4 to 7ni4 copying progra$

 #nd there are corresponding definitions for the severity-

•

AD<7EE(< L Messages that indicate a disaster scenario

•

AD<7+AE(* L Messages that indicate i$$ediate attention

•

AD<7:(=* L Messages that indicate a critical condition that needs addressed

•

AD<7E(( L Messages that indicate an error 

•

AD<7'+(>=>< L Messages that indicate a warning

•

AD<7>D*=:E L or$al $essages but considered i$portant

•

AD<7=>D L Infor$ational $essages

•

AD<7?EB8< L Eebugging or diagnostic $essages

ow lets us see what happens when we log a $essage Fi&clude stdio5J Fi&clude s,slog5J i&t mai&.i&t argc car Rarg/ST  s,slog.AD<78)E( | AD<7?EB8< ";ello 'orldK"Y 

ince we are logging to AD<78)E(, once run, we can look at the end of the /arloguser5log file and we will seea&

1 1#2331 cip2 a5out ;ello 'orldK

f course, the destination of the $essage is governed by the configuration of rs,slogd and this log file is only the default ee also•

rsyslog ho$e page

•

$an8B9 L d$esg

Page 1$/

Performance !hen running your applications, if they are not running fast enough, or stutter or run out of $e$ory, you need to perfor$ so$e perfor$ance analysis Fortunately, :inu4 has $any tools and utilities at your disposal to do 6ust that

"esource Utili7ation If we have perfor$ance issues, the chances are that we $ay be constrained on resources  #s such, we want to deter$ine how to $easure the resources we are using and have available #emory .tili%ation "unning /mstat produces a /uick su$$ary of virtual $e$ory availability$ /mstat procs -----------memor,---------- ---s%ap-- -----io---- -s,stem-- ------cpu----r b s%pd free buff cace si so bi bo i& cs us s, id %a st 0 0 0 1600!2 0 1!1662 0 0 0 0 2030 40#6 H ! G# 0 0

(he colu$n called free shows us the nu$ber of bytes unused "#M for our applications In this e4a$ple, we see 1=002 bytes ince we have a large a$ount of free ra$, we would not e4pect to be using any swap space and this is backed up by the s%pd colu$n $ top + similar comma&d is te first fe% li&es of te top comma&d5 top - 00004H up 106 4 users load a/erage 0512 051H 0514 *asks 1H2 total 2 ru&&i&g 1H0 sleepi&g 0 stopped 0 Combie :pu.s 1H54 us 1251 s, 050 &i H654 id 050 %a 050 i 450 si 050 st NiB em !03H32 total 333G2G used 1H#G04 free 0 buffers NiB )%ap 0 total 0 used 0 free5 1!1G3H caced em

In this line 8taken fro$ above9NiB em

!03H32 total

333G2G used

1H#G04 free

0 buffers

!e see that we have a total a$ount of "#M of 203@ bytes of which 333BB is used and 1@B<0C is free (he output here contains $ore details than /mstat as it shows us the total a$ount of "#M and used "#M as well as unused "#M  #gain, looking at the following line, we see that we have no swap space being used NiB )%ap

0 total

0 used

0 free5

1!1G3H caced em

ince :inu4 supplies virtual $e$ory, this $eans that each process sees its own address space as though it were the only application in the $achine ince the operating syste$ itself  is $anaging $e$ory, if the accu$ulation of $e$ory usage across all the progra$s running on your HIP starts to get close to the total a$ount of "#M available, the HIP can start paging out "#M to storage +y writing pages of "#M to storage, the operating syste$ can free up those pages for use by other applications (he thinking here is that there will be so$e applications that are holding on to "#M but are the$selves not actively using it Perhaps these applications sleep for long periods of ti$e or are de$on progra$s ither way, the chances of the$ accessing the page of "#M that has been swapped out to disk is believed to Page 1$

be lower than that of other applications hould those applications later need to access the pages of "#M that have been swapped out, so$e other application will have so$e of its pages swapped out and the "#M released by that swapped used to hold the original progra$'s swapped out pages (he algorith$s in play here that decide which pages get swapped out is beyond our discussion Fro$ a perfor$ance perspective, it is not necessarily a bad thing to see swap space being used It si$ply $eans that our co$bined applications are needing $ore physical "#M than we actually have and the swap space is being used to provide an illusion that we have enough However, we can enter a situation where we get so low on available "#M relative to the needs of the applications that we spend $ore and $ore ti$e swapping in and out pages of "#M than doing productive work uch a circu$stance is called thrashing Nour Pi as a whole will start to feel sluggish at this point hould your applications consu$e $ore and $ore "#M, you can i$agine that $ore and $ore of their pages will be swapped out ince the a$ount of disk space allocated to holding swapped out pages 8called the swap space9 is of a finite and fi4ed si%e, we can reach a state where we have filled all our real "#M and also filled the disk space allocated for swap space  #t that point your HIP is in trouble It can no longer allocate e4tra space for $e$ory re/uests and applications will start to fail "aspbian will start to ter$inate applications to free up their resources

Performance Commands top (he top co$$and is a real)ti$e te4t.full)screen application that shows the current syste$ state as well as the processes currently running and their resource consu$ption-

Here is an e4a$ple screen capture-

Page 1$$

ne should spend /uite so$e ti$e studying the $anual page to beco$e skilled in the $eaning of each of the options !ithout e4plaining where you can see the$, the top output includes P7 utili%ation, how the P7 is being used, how $uch $e$ory is free, the list of top running processes, how $any processes are active & and $uch $ore ee also•

top819 ) :inu4 $an page

vmstat (he /mstat co$$and logs statistics about nu$ber of processes, virtual $e$ory utili%ation, swap space, I traffic, and P7 usage $ /mstat procs -----------memor,---------- ---s%ap-- -----io---- -s,stem-- ------cpu----r b s%pd free buff cace si so bi bo i& cs us s, id %a st 2 0 0 1H#!4G 0 1!1#G4 0 0 0 0 1G63 36#0 H 6 G6 0 0

ee also•

$an8B9 L v$stat

&ask #anager  #n J application called *(ask $anager* is pre)installed to provide an J based task $anager tool-

Page 1$)

!hen ever I have atte$pted to use it, its output appears corrupted but  worse  it see$s to consu$e the $a6ority of the available P7 cycles  and since our goal is to $onitor resource utili%ation, this see$s a bit pointless

gnome-system-manager  #n attractive syste$ $anager tool is available called *gno$e)syste$)$anager* (his is not installed by default but can be installed through$ sudo apt-get i&stall g&ome-s,stem-ma&ager

!hen run, it shows a task list-

and it can also show resource utili%ation-

Page 1$,

(he down side of this app is that it consu$es a lot of P7 6ust by itself

time !hen we run a co$$and fro$ the shell pro$pt, we $ight want to know how long it took and also how $uch of that ti$e was spent in different areas (he co$$and *ti$e* takes as a para$eter a co$$and to run (he co$$and is e4ecuted and, at the end, we get a report of what P7 utili%ation and elapsed ti$e the e4ecution of the co$$and took For e4a$ple, when I ran an install of a an np$ $odule that involved co$pilations, here is the resultreal user s,s Page 1$<

Hm2564#s !m250H0s 0m4G5H4!s

Performance characteristics of different programming languages (here is usually a trade)off between progra$$ing abstraction levels and perfor$ance !e know that a Pi runs a P7 and that the P7 e4ecutes P7 instructions If we were to write our applications directly in asse$bly language then we would likely achieve opti$al perfor$ance However, in reality, we find that is rarely done (he reason for that is that we are willing to sacrifice that level of perfor$ance for the ti$e, ease and $aintainability of the source code itself (his is a story that repeats for higher and higher levels of abstraction For  e4a$ple, si$ple  progra$$ing translates pretty efficiently to asse$bly language but yet  is both portable across P7s and gives us higher levels at which to work 7p fro$  is KK adding an b6ect riented flavor #gain, KK translates to asse$bly language and hence native e4ecutable code Further up the scale we $ove away fro$ natively e4ecutable code to interpreted code such as ?avacript Here we have new paradig$s that don't have e/uivalents in the instruction sets of processors such as la$bda functions and closures & features which our hu$an $inds can use to si$plify our algorith$ic tasks when writing progra$s but which take $ore e4ecution resources to achieve (ypically these interpreted progra$s are parsed at run)ti$e !ith so$e advanced interpreters, co$pilation is done on the fly or 6ust in ti$e and with other interpreters, no co$pilation is perfor$ed and the instructions are si$ply re)interpreted each ti$e they are e4ecuted +etween interpreted and native e4ecutable code there are languages such as ?ava which co$pile their source code to a fictitious asse$bly language for a P7 architecture which does not e4ist in hardware Instead a software application called a Dirtual Machine *e4ecutes* these co$piled instructions in software (he advantage here is that a progra$ co$piled once to produce these *bytecode* applications is portable to all platfor$s which have i$ple$ented the virtual $achine & irrespective of the underlying hardware P7 that is actually e4ecuting the virtual $achine (he choice of progra$$ing language you use will $ost co$$only be $ade based upon your own skills and e4perience with one or the other In addition, if you are using speciali%ed and pre)e4isting libraries, they $ay only be available for a subset of languages 8or even only one9 However, when one writes a progra$ & no $atter how elegant that progra$ $ay be, if it doesn't *work* then it is useless If we write an application and it takes too long that users aren't prepared to use it & or worse, it is driving hardware co$ponents so slowly that they the$selves si$ply don't operate & then we $ay be forced to change fro$ our higher level language of choice down to lower level but $ore efficient languages (here are also ti$es where we can design around perfor$ance proble$s while keeping high level concepts (he trick here is to deter$ine why an application is not perfor$ing as we desire and see if we can't alleviate those proble$s with better coding design 4a$ples $ight include the use of $ulti)threading to perfor$ $ultiple tasks in parallel or we $ight e$ploy $i4ed languages For e4a$ple a progra$ written in ?ava can invoke subroutines written in  (hese subroutines could encapsulate the tasks that are e4pensive in ?ava

Page 1$9

Hardware Interfacing Terminal connections +efore we say anything else  I want to say very clearly  the API pins on the HIP are 33D "epeat after $e  the API pins on the HIP are 33D (hey are ( 2D tolerant (he reason I $ention this  and I will $ention it again  is that one of the /uickest ways to da$age or destroy your HIP is to connect a 2D source to a API pin Eon't do it Eon't even think of doing it heck, check and double check when you wire up a pro6ect that you haven't done it 8by accident9 (he HIP has two sets of sockets ne on the left of the board and one on the right ach set of sockets is co$posed of C0 ter$inals giving us B0 ter$inals in total (o be able to discuss these ter$inals we have to define a na$ing and nu$bering sche$e (he one chosen is that the ter$inals on the left 8with the 7+ at top9 are called the 713 ter$inals while the ter$inal on the right are called the 71C ter$inals !e choose to nu$ber and na$e these as followsU1/ *=5

1

2

CH*I=

#CC$#

/



*=5

#CC/#/

$

)

T+

#CC1#<

,

<

B%T

T7I1+5% – I2C bus 1 data

9

10

P73=

T7I1+C& – I2C bus 1 clock

11

12

*=5

E1

1/

1

E2

G1

1$

1)

G2

8C552

1,

1<

P7:0 – Pulse 7idth :odulation

8C55

19

20

8C55/

8C55)

21

22

8C55$

8C5510

2/

2

8C55,

8C5512

2$

2)

8C5511

8C551

2,

2<

8C551/

8C551<

29

/0

8C551$

8C5520

/1

/2

8C5519

8C5522

//

/

8C5521

8C5C8&

/$

/)

8C552/

8C5#+G=C

/,

/<

8C5H+G=C

*=5

/9

0

8C556

Page 1)0

U1 *=5

1

2

#CC$#

U%'T1TE

/



HP8 – Head!hones let

U%'T1'E

$

)

HPC3: – Head!hones coon

-68

,

<

HP' – Head!hones right

#CC/#/

9

10

:IC:

8'%5C – %5C in!ut

11

12

:ICI=1

EI3P0

1/

1

EI3P1

EI3P2

1$

1)

EI3P/

EI3P

1,

1<

EI3P$

EI3P)

19

20

EI3P,

*=5

21

22

*=5

%P6I=T1

2/

2

%P6I=T/

T7I2+5% – I2C bus 2 data

2$

2)

T7I2+C& – I2C bus 2 clock  

C+IPC&

2,

2<

C+IC&

C+IH+G=C

29

/0

C+I#+G=C

C+I50

/1

/2

C+I51

C+I52

//

/

C+I5/

C+I5

/$

/)

C+I5$

C+I5)

/,

/<

C+I5,

*=5

/9

0

*=5

 

Fro$ another perspective-

(hese ter$inals are e4posed in two banks of sockets I have a concern 8which $ay be irrational9 that plugging in and out breadboard wires into these sockets will weaken the$ (o Page 1)1

solve that, I bought sets of e4tension sockets that look as follows-

(here are C0 pin fe$ale sockets with long legs (hese can be pushed into the HIP headers and then the breadboard wires pushed into these e4tensions hould these upper sockets wear out, I can pull these and plug in new instances #n e4tender header can be found on e+ay for about ;0<0 each !hen plugged into HIP, they look as follows-

+ecause the pins are so long, you can also solder these headers onto a strip board or P+ and have the co$ponents *face)up* while docked to the headers underneath #n advantage of that is that during asse$bly, you don't have to invert your thinking with $irror i$ages of what pins go where

$PI+ interfacing ne of the great 6oys of HIP is that you can build pro6ects that involve your own electronics Nou can attach sensors, :Es, and $uch $ore to the HIP APIs are the Aeneral Purpose Page 1)2

Input.utputs (hey provide the pri$ary $echanis$ to read and write electrical signals to and fro$ the HIP

GP+O theory (he theory of Aeneral Purpose Input.utput 8API9 is the si$plest of all the hardware interfaces to understand !ith API a device e4poses a set of physical pins (hese pins can either be used to output an electrical signal for consu$ption by a second device connected to the pin or can be used to read the electrical signal present on a pin as set by a second device #t any one ti$e, each pin can either be defined as an output pin or an input pin bviously it can't be both at the sa$e ti$e though $ay switch roles as needed !hen a pin is flagged as output, it can source a current that can be consu$ed by a connected peripheral however care $ust be taken APIs on M7s are only able to source a s$all a$ount of current and trying to draw too $uch can irreparably da$age the device (ake care to consult the appropriate data sheets for any devices connected to deter$ine their current re/uire$ents and ensure that you are not asking for too $uch current fro$ your M7

GP+O on )*+P 4posed fro$ the 71C header on HIP are B ter$inals labeled JI)P0 to JI)P= (hese are available for API usage #ccess to these ter$inals is through (!I bus  and the device address 0x3G

For progra$s that wish to access the API, HIP uses the *API ysfs* interface In nglish, what that $eans is that access to the APIs is perfor$ed through file syste$ operations in the directory tree starting at s,sclassgpio If we look in this directory we will find lots of *things* and we will gloss over $ost of the$ However, here is the general idea & !e have B APIs with which we $ay wish to work +y default,  of the$ are e4posed for our usage & but we can access which ones we want by writing the te4t of the API we want to work with into the file called s,sclassgpioexport It would be ideal that if we wanted to work with JI)P3 we $ight e4ecuteeco "3" J s,sclassgpioexport

but life in progra$$ing is never that si$ple Instead we have to add a *base value* to our desired API (o $ake $atters worse, the base varies whether we are running on a C3 or a CC kernel If we are running on a C3, the base is C0B If we are running on CC, the base is 101@ Making this e4plicit, if we are running on a C3 kernel and want to interact with JI)P3, we would runeco "411" J s,sclassgpioexport

Page 1)/

GPIO Identity

4.3 Value

4.4 Value

EI3P0

0<

101)

EI3P1

09

101,

EI3P2

10

101<

EI3P/

11

1019

EI3P

12

1020

EI3P$

1/

1021

EI3P)

1

1022

EI3P,

1$

102/

(he act of writing the value into the e4port file causes a new directory structure to appear in s,sclassgpio (he na$e of the new directory is *gpio/alueJ* For e4a$ple, if we write *411* into e4port, then a new directory called s,sclassgpiogpio411 will be found !ith a gpio ter$inal directory, we find the $eat of the file we need First let us look at the file called *directio&* If we read fro$ this file we will find a value of either ' i&* or *out* (he value *i&* $eans that the API is in input $ode If the value is * out*, then the API is in output $ode !hen a API is in input $ode, if read fro$ the file called * /alue* we will either get *0* or *1* reflecting the signal level found on the ter$inal If the direction $ode is *out* then the signal found on the ter$inal will either be *0* or *1* depending on what we write into */alue* (he file called * edge* is the value of the pin that will cause a * poll.* call to return Dalues can be-

•

none

•

rising

•

falling

•

both

ee also•

(he sysfs file syste$

•

API, PI and I fro$ 7serspace, the (rue :inu4 !ay

/'I0 using libsoc

(he libsoc library provides API functions for  progra$s (o use these functions, we start with a call to libsoc7gpio7reUuest. (his function returns to us a *gpio* pointer which is the handle we need on further API calls (he para$eters are the id of the API to access and the $ode of access If we wish to clean up after ourselves, we will invoke libsoc7gpio7free.

Page 1)

!hen we re/uest a API, we haven't yet said whether or not we re using it for input or output !e $ust now set the direction with a call to libsoc7gpio7set7directio&. (he direction will be either =>P8* or D8*P8* (o deter$ine the current direction of a API we can call libsoc7gpio7get7directio&. (he value of an output API can be set with libsoc7gpio7set7le/el. and the value of an input API can be read with libsoc7gpio7get7le/el. (he values can be :! or HIAH !e $ight not want to continually poll a API but instead wait for so$e event to happen such as a change in value !e have a function called libsoc7gpio7%ait7i&terrupt. which will block waiting for an interrupt to occur or a ti$eout to pass If we don't want to block, we can call libsoc7gpio7callback7i&terrupt. to register a callback function that will be invoked when an event happens !e can cancel a previously registered callback handler with a call to libsoc7gpio7callback7i&terrupt7ca&cel. !hat we consider to be an event that will register an interrupt is also settable by us via the libsoc7gpio7set7edge. function (riggers including-

•

"IIA L ignal goes low to high

•

F#::IA L ignal goes high to low

•

+(H L ignal transitions in either direction

•

 L o triggering

ee also•

libsoc L gpio

•

+uilding libsoc

/'I0 using Node.s

 #s is always the case in ?avacript and hardware interfacing, ?ohnny)Five is usually our first port of call and API is no e4ception (he Pin ob6ect provides e4cellent access to the $a6ority of pins on HIP Here is an e4a$ple that alternates the signal on a Pin which could blink a led/ar fi/e 9 reUuire.WIo&&,-fi/eWY /ar cipio 9 reUuire.Wcip-ioWY /ar board 9 &e% fi/e5Board. io &e% cipio. Y board5o&.Wread,W fu&ctio&.  /ar pi& 9 &e% fi/e5Pi&."@=D-P0"Y /ar b 9 trueY set=&ter/al.fu&ctio&.  if .b    pi&5ig.Y Page 1)$

 else  pi&5lo%.Y  b 9 KbY  1000Y Y  

 #s an alternative to ?ohnny)Five, there is a package called *cip-gpio* that provides API support fro$ ?avacript (his $odule e4poses API through the following #PIs-

•

Apio8gpio, directionO, edge9

•

read89

•

write8value9

•

watch8callback9

•

unwatch8Ocallback9

•

setEirection8direction9

•

edge89

•

setdge8edge9

•

une4port

(he *cip-gpio* package is loosely based on the very popular * f/dio&off* package (his can be installed with$ &pm i&stall o&off

ee also•

np$ L chip)gpio

•

np$ L onoff 

I9C (he Inter)I 8I9 protocol is is used for connecting $ultiple devices together that provides a way to trans$it B bit bytes over a serial bus link riginally developed by Phillips e$iconductors it is now part of JP e$iconductors #n alternate na$e for I is the (wo !ire Interface 8(!I9 (his is so)called because there are only two lines needed for co$$unication I is i$portant for us as there are $any interesting co$ponents that use this protocol to which we $ay wish to attach

+6) theory (he I interface is a serial interface technology for accessing devices (he protocol is also called the (wo !ire Interface as it uses only two signal bus lines (hese signal bus lines are Page 1))

called )?+ 8Eata9 and ):A 8lock9 I allows for bidirectional co$$unication #ttached to these lines are devices that wish to co$$unicate ne device holds a special role and is known as the bus $aster It is the $aster that is the coordinator of all activities and is responsible for generating the clock #ll other devices attached to the bus are known as slave devices

(he data trans$ission rates are up to 100kbits.second in standard $ode and C00kbits.second in fast $ode ach slave device has a distinct and uni/ue address upon the bus It is the $aster that always initiates co$$unication which $ay be either a send re/uest to send data to a specific slave or a read re/uest which asks the slave to respond with specific data 7nless the $aster  e4plicitly addresses a slave, it must keep silent nly the slave that has been instructed to do so $ay trans$it data on the data line (he device addresses are co$$only = bits in si%e (he $aster sends the address of the device with which it wishes to co$$unicate I$$ediately following the address is a bit that indicates whether this is a read re/uest 819 or a write re/uest 809 +

+

+

+

+

+

+

(  '

+ecause of this encoding, take care when reading data sheets and looking at the address of a device o$eti$es addresses are written as values fro$ 0x00 L 0x6f describing the device address while so$eti$es addresses are described as values fro$ 0x00 L 0xff which include the read . write bit For e4a$ple & the following are all correct-

•

(he device has address 0x1e

•

(he device can be read fro$ 0x3d

•

(he device can written to 0x3c

(he buses are *open collector* with an active low (his $eans that pull)up resistors should be attached to the lines to ensure that they are logic high by default (here are hundreds of devices which are I capable Here is a selection broken out by categoryPage 1),

ccelerometers! Gyroscopes! Compass

H:C$<
Co!ass

:PU)0$0 ?*G$21@

%cceleroeter and *yrosco!e

::%,$$

%cceleroeter  

Data sensors

B:P1<0

Te! and !ressure

P"# controllers

PC%9)<$

1) !ort P7:F+ero controller  

GPIO $%tenders

PC-<$,

< bit *PI3 etender  

:CP2/01,

1) bit *PI3 etender  

nalo& to Di&ital

%5+101$

%nalog to digital

udio

T6%),),

-: 'adio

Real time cloc' 

5+1/0,

'eal tie clock  

Fro$ a signal perspective the E# line will be read when the clock goes high (he signal on the E# line $ust not change while the clock is high 8with the e4ception of the stop bit $arker9 !hen the clock goes low, the E# line can be changed to represent the ne4t bit of data to be trans$itted  #t any one ti$e, the $aster will be in co$$unication with either no slave or e4actly one slave (his sounds very acade$ic but is i$portant to understand If we think of an initially idle environ$ent, then the $aster is not co$$unicating with any slaves !hen the $aster now wishes to send data to a slave, it will begin a *transaction* For the life of the transaction, the $aster $ay only now co$$unicate with that one slave (he start of a transaction is indicated by a transition fro$ high to low on the E# line while the clock is high (his is one of only ti$es that the E# line can change its state while the clock is high and is reserved for a start indication  # second indicator signal called the stop signal is used to indicate the end of a transaction (his is flagged by an E# signal line change fro$ low to high while the clock line is high  #fter every B bits of data are trans$itted, the receiver of the data $ust generated an acknowledg$ent (he acknowledg$ent is sent by the receiver and consists of a low value during the high period of the clock If the receiver detects a situation that it considers and error, it can send a negative acknowledg$ent by bringing the E# high low during the high period of the clock Eata trans$ission is M+ to :+  # su$$ary of the trans$ission fro$ $aster to slave and slave back to $aster for both read and write re/uests is shown ne4t-

Page 1)<

ee also•

!ikipedia L I

•

I)bus specification and user $anual

•

Nou(ube- How I o$$unication !orks and How (o 7se It with #rduino

+6) on )*+P HIP is 33D device #s such be very careful when connecting to a 2D based I device If HIP is a $aster, then you can connect the HIP I clock to the input :5 on the 2D slave but do not directly connect the E# lines between a 2D slave and HIP Instead, place a level shifter between the$

(here are two distinct buses for I e4posed on HIP (hese are three buses HIP shown as +us 0 and +us  8as listed by i2cdetect -l9 However, that is a $o$ent in ti$e story +us 0 should not be e4posed as it is used for internal operations +uses 1 and  are for user applications but, due to a believed error, the current CC 5ernel e4poses buses 0 and  (he tools for I are in the apt-get package called i2c-tools If these tools are not installed, further co$$ands such as i2cdetect will not be found (o install these tools, run$ sudo apt-get i&stall i2c-tools

!hen using I we have the notion of a bus with devices attached to this bus Ideally, we know the identity of the device on the bus but if we aren't sure and.or want to verify that the device is present, we can use the i2cdetect co$$and (his co$$and can send the start of an I trans$ission to each of the possible addresses on the bus +y I protocol, when we send an address, the device should respond with an acknowledg$ent that it is ready to proceed +y sending the start of a protocol re/uest to each device, the principle is that those that respond are obviously present and we have thus deter$ined which devices are present on the bus !e can't tell what the device actually is & only that it is there Here is an e4a$ple of i2cdetect output$ i2cdetect -, 0 0 1 2 3 4 Page 1)9

!

H

6

G

#

a

b

c

d

e

f

00 10 20 30 40 !0 H0 60

--------

--------

--------

---------

---------

---------

---------

---------

------HG

--------

--------

--------

--------

--------

--------

--------

"unning this co$$and is  potentially  dangerous as we are trusting that each of the devices on the bus won't be confused if it $erely receives the start of an I re/uest that i$$ediately ends without further interaction In practice, we know of no real)world circu$stances that cause any proble$s  #nother useful co$$and is i2cdump (his takes the bus nu$ber and the slave address and returns the values of all registers addressable fro$ the device Here is an e4a$ple of output$ i2cdump 0 1 00 G3 01 10 3a 00 20 00 00 30 00 00 40 fc ec !0 00 00 H0 00 00 60 00 00 G0 G3 01 #0 3a 00 a0 00 00 b0 00 00 c0 #0 ec d0 00 00 e0 00 00 f0 00 00

-, 2 01 00 00 00 20 00 00 00 01 00 00 00 00 00 00 00

0 0xHG b 3 4 ! 0d 21 0e 00 00 00 00 00 00 00 00 00 fe c6 00 00 00 00 00 00 00 00 00 HG 0d 21 0e 00 00 00 00 00 00 00 00 00 fe c4 00 00 00 00 00 00 00 00 00 HG

H ec 00 00 00 4f 00 00 00 ec 00 00 00 !3 00 00 00

6 24 00 00 00 00 00 00 00 24 00 00 00 00 00 00 00

G 0! 00 00 00 #4 00 00 00 0! 00 00 00 #b 00 00 00

# f# 00 00 00 00 00 00 00 f# 00 00 00 00 00 00 00

a 03 00 00 01 00 00 00 00 03 00 00 01 00 00 00 00

b fH 00 00 fc 00 00 00 00 fH 00 00 fc 00 00 00 00

c 2G 00 00 00 00 00 00 00 2G 00 00 !c 00 00 00 00

d 4c 00 00 ff 00 00 00 00 4c 00 00 ff 00 00 00 00

e He 00 00 #c 00 00 f0 00 He 00 00 34 00 00 f3 00

f #2 00 00 3b 00 00 #0 00 #2 00 00 3b 00 00 !0 00

01234!H6G#abcdef ````K``$````.A&` 555555555555555 5555555555555555 5555555555``55`Y `` ``5D5`5555555 5555555555555555 55555555555555`` 555555555555555 ````K``$````.A&` 555555555555555 5555555555555555 5555555555``^54Y ``5``5)5`5555555 5555555555555555 55555555555555`P 555555555555555

In addition, there are two further co$$ands called i2cget and i2cset that read and write fro$ the I bus Fro$ the shell, we have a couple of co$$ands that can be used to read and write to an I slave device (he first is i2cset (here are options on it but the si$plest is$ i2cset -, 0 addressJ data+ddressJ S/alueTR =

n bus , a PFB2=C 8API e4tender9 can be found at address 0x3G  #t a low level, I can be accessed through  language reads and writes co$bined with ioctl For each of the buses e4posed by HIP, we will find a corresponding entry in de/ n $y device, there are two buses labeled 0 and  !hen I run *icdetect )l*, the following is returnedi2c-0 i2c i2c-2 i2c

m/H4xxx7i2c adapter m/H4xxx7i2c adapter

if we then look in de/, we will find two files called-

•

Page 1,0

.dev.ic)0

=2: adapter =2: adapter

•

.dev.ic)

 #ccess to the bus can be achieved through access to these files ote the per$issions on the files are read.write for root and the group called ic First we $ust include li&uxi2c-de/J to be able to access the I related constants !ith that done, we can open the appropriate de/i2c-x file (o specify which device on the bus we are going to work with, we e4ecute an ioctl co$$and that looks as followsioctl.fd =2:7)A+E de/ice+ddress

ote that if we specify an invalid device address, we don't get an error indication nce the address has been supplied, we can perfo$ reads and writes to read and send data If we need to $i4 activities in a single transaction, we can useioctl.fd =2:7(?'( struct i2c7rd%r7ioctl7data Rmsg)et

(he struct i2c7rd%r7ioctl7data contains-

•

struct i2c7msg Rmsgs L #n array of $essages

•

i&t &msgs L (he count of $essages in $sgs

ach of the struct i2c7msg contains-

•

7u1H addr L lave address

•

7u1H flags L I control flags ◦ =2:77(? L "ead data ote that there is no =2:77'(  if =2:77(? is not specified then write is assu$ed

•

7u1H le& L :ength of the $essage buffer pointed to by buf 

•

7uG Rbuf L Pointer to data

ee also•

ic)dev interface

•

$an89 L ioctl

•

:evel shifting techni/ues for I bus design

I(C with libsoc

(he libsoc library provides a set of I interfaces for  applications !e initiali%e an I attach$ent with a call to libsoc7i2c7i&it. (his na$es both the bus and the address of the device on the bus which we wish to access (he return fro$ this is a pointer to an ic ob6ect that represents the handle we have to pass in to subse/uent calls !e can clean up before ter$ination with a call to libsoc7i2c7free. !e can write to a device using libsoc7i2c7%rite. and read data using Page 1,1

libsoc7i2c7read. !e can set a ti$eout for an I re/uest using libsoc7i2c7set7timeout.

I(C with Node.s

Fro$ within the ode6s environ$ent there are a nu$ber of np$ packages that provide I access f these, $y current favorite is called *ic* ee also•

np$ L ic

P.* P# theory (he idea behind pulse width $odulation is that we can think of regular pulses of output signals as encoding infor$ation by how long the signal is kept high vs low :et us i$agine that we have a period of 1H% 8one thing per second9 ow let us assu$e that we raise the output voltage to a level of high for [ of a second at the start of the period (his would give us a s/uare wave which starts high, lasts for 200 $illiseconds and then drops low for the ne4t 200 $illiseconds (his repeats on into the future (he duration that the pulse is high relative to the period allows us to encode an analog value onto digital signals If the pulse is 100 high for the period then the encoded value would be 10 If the pulse is 100 low for the period, then the encoded value would be 00 If the pulse is on for *n* $illiseconds 8where n is less than 10009, then the encoded value would be n.1000

(ypically, the length of a period is not a whole second but $uch, $uch s$aller allowing us to output $any differing values very /uickly (he a$ount of ti$e that the signal is high relative to the period is called the *duty cycle* (his encoding techni/ue is called *Pulse !idth Modulation* or *P!M* (here are a variety of purposes for P!M o$e are output data encoders ne co$$only seen purpose is to control the brightness of an :E If we apply $a4i$u$ voltage to an :E, it is $a4i$ally bright If we apply [ the voltage, it is about [ the brightness +y applying a fast period P!M signal to the input of an :E, the duty cycle beco$es the brightness of the :E (he way this works is that either full voltage or no voltage is applied to the :E but because the period is so short, the *average* voltage over ti$e follows the duty cycle and even though the :E is flickering on or off, it is so fast that our eyes can't detect it and all we see is the apparent brightness change ee also•

Page 1,2

!ikipedia L Pulse)width $odulation

P# on )*+P adly, it is not currently present in the kernels pre)built for HIP (o consu$e easily, we are going to have to be patient

U"T /%erial0 Interface .(& theory  # 7#"( is a $echanis$ to trans$it and receive parallel data over a serial line connection (he data being trans$itted is seriali%ed into a se/uence of bits and sent down the wire (he receiver receives the bits and asse$bles the$ back into the original data +oth the sender and receiver pre)agree on the trans$ission rate of the data (his is called the baud rate +efore data is trans$itted, a start bit is flagged on the wire to indicate that data is about to follow (hen co$es the B bits of data followed by a single stop bit It is the start bit that allows the sender and receiver to synchroni%e on their clocks for the re$aining bits (he idle state of a serial line is high (here is also the option of supplying parity bits and other control infor$ation

o$e baud rates that are co$$on are <@00, 1<00, 2=@00 and 11200 "e$e$ber that these are bit trans$ission rates and not byte rates ince a single byte will have at least two additional bits 8start and stop9, this $eans that there are 10 bits to be trans$itted for each byte #s such, a baud rate of <@00 $ay $ean <@0 8<@00 . 109 bytes per second as opposed to 100 8<@00 . B9 bytes per second ee also•

!ikipedia- 7niversal asynchronous receiver.trans$itter 

.(& on )*+P HIP has a 7#"( that it e4poses on ter$inals 3 and 2 of the 71C connector (here are three ter$inals ne4t to each other which are AE 819, 7#"(1)(J 839 and 7#"()"J829 which are  6ust what we need (he serial port is e4posed in the file syste$ at de/tt,)0

+y default, the 7#"( is used to provide a ter$inal for access (his $eans that there is already an application reading and writing to it (hat application is an instance of the :inu4 gett, progra$ which is handling ter$inal access (here are going to be ti$es when we want to use the 7#"( for our own I. purposes and hence it will be our application that needs access to it ince we can't have two progra$s thinking they have control over the 7#"(, we $ust disable the gett, progra$ (his is registered as a service which can be stopped withsudo s,stemctl stop serial-gett,Vtt,)05ser/ice

it can be disabled with sudo s,stemctl disable serial-gett,Vtt,)05ser/ice

(he default speed 8baud rate9 of the serial interface is 11200 Page 1,/

Euring boot, HIP writes the boot $essages to serial (his is great if we are doing debugging but if we are building a pro6ect, the te4t of the console log sent to serial will likely confuse our partner device listening to HIP # recipe to resolve this is still being sought Fro$ a ode6s environ$ent we can use the serialport np$ package !e can look at the settings for the serial port using$ sudo stt, - de/tt,)0

ee also•

onnecting to HIP using a serial connection

•

np$ L serialport

U%B (he nature of 7+ devices can be found with the lsusb co$$and Fro$ there, you can add the -/ 8verbose9 option and filter with the -s de/>um option For e4a$ple, here is an output fro$ lssubBus Bus Bus Bus

002 001 001 003

?e/ice ?e/ice ?e/ice ?e/ice

001 002 001 001

=? =? =? =?

1dHb0001 1e4e0110 1dHb0002 1dHb0002

Ai&ux ou&datio& 151 root ub :ubeter&et Ai&ux ou&datio& 250 root ub Ai&ux ou&datio& 250 root ub

!hen we look at the output of a 7+ listing, we so$eti$es see pairs of nu$bers In the above, we can see 1e4e0110 (he first of these nu$bers is called a vendor id and each product vendor has been allocated a uni/ue code (he second nu$ber is a product id and corresponds to a product registered by that vendor !hen a 7+ device connects to a co$puter, the co$puter can /uery these codes and learn what kind of device it is that has attached !e can use this vendor.product pair as keys in a web look)up to deter$ine $ore details about that device # website such as http-..thes%diecrueu.content.usbidphp will allow us to enter the vendor.product pair and retrieve its details hould one need $ore 7+ sockets than the single one provided and don't want to use an e4ternal 7+ adapter, a product called *Uueso III* is available that adds four additional 7+ ports

Page 1,

ee also•

$an8B9 L lssub

•

Uueso III L C port 7+ e4tender 

Bluetooth HIP has native +luetooth support (his $eans that HIP can interact with +luetooth devices such as keyboards, $ice and cell phones :et us review what +luetooth $eans for us +luetooth is a wireless co$$unication protocol.technology that provides data transfer over a radio signal :et us assu$e that HIP is one end of the connection and any other +luetooth device can be the other For security purposes, arbitrary +luetooth devices can't si$ply  be LusedL "ithout soe e!licit authori;ation. -or ea!le4 it "ould be ery "rong i I could bring y Bluetooth headset near your !hone and start listening to your calls. To achiee security4 a !rocess called L!airingL needs to be  !erored. The achiees a leel o trust bet"een the t"o Bluetooth deices such that they reeber allo"ing subseuent connection "ithout haing to be re!aired.

Packages of interest-

•

bluetooth

•

blue%

•

blue$an L # gui package that $ay be un)stable

!e can check the status of our bluetooth de$on with$ sudo s,stemctl status bluetoot X bluetoot5ser/ice - Bluetoot ser/ice Aoaded loaded .libs,stemds,stembluetoot5ser/iceY e&abled +cti/e acti/e .ru&&i&g si&ce *u 201H-0G-04 213633 :?*Y 2 10mi& ago ?ocs ma&bluetootd.G  ai& P=? 3G# .bluetootd )tatus "(u&&i&g" :
04 04 04 04 04

213633 213633 213634 213634 213634

cip2 cip2 cip2 cip2 cip2

bluetootdS3G#T bluetootdS3G#T bluetootdS3G#T bluetootdS3G#T bluetootdS3G#T

Bluetoot daemo& !523 )tarti&g )?P ser/er Bluetoot ma&ageme&t i&terface 1510 i&i555ed )ap dri/er i&itialiCatio& failed5 sap-ser/er Dperatio& &ot permitted .1

"luetooth specification +luetooth is a specification for wireless co$$unication between $ultiple electronic devices  #t present, there are two pri$ary standards & these are +luetooth 8lassic9 and +luetooth : (he *:* stands for :ow nergy and is the specification for devices that wish to be powered by si$ple batteries and yet have sufficient life span

In the +luetooth story, we have devices which are *$asters* and devices which are *slaves*  # slave can only for$ a connection and co$$unicate with a $aster while a $aster can for$ Page 1,$

concurrent connections with $ultiple slaves ne slave can not directly co$$unicate with another slave Instead it $ust co$$unicate with the $aster and the $aster relay the re/uest (he si$plest co$$unication is one $aster and one slave but if we have $ultiple slaves connected to the sa$e $aster, the resulting *network* is ter$ed a *piconet* ach device that participates in the conversation has a uni/ue address that is a CB bit value co$$only written as 1 he4 values (his address is known as the *+luetooth Eevice  #ddress* and $ay be seen in other docu$entation abbreviated to *B?7+??(* (he encoding of a +luetooth address is that the first C bits encode the organi%ation responsible for allocating the re$aining address and the re$aining C bits are the address itself However the full CB bits are the co$plete identity of the device  #s well as having a uni/ue address, each device can have a sy$bolic na$e to help us $eaningfully identify it (his is ter$ed the display na$e (he display na$e is only a $apping to a +luetooth address and it is really the address that is used to distinguish one device fro$ another It is also i$portant to note that there are no uni/ueness constraints on device na$es Multiple devices $ay select the sa$e device na$e :et us assu$e that initially, we have two devices and neither of the$ know about the other !hat $ust now happen is a discovery process ne of the$ will broadcast an *in/uiry* re/uest Eevices receiving the in/uiry can respond with their own e4istence by trans$itting their own address and possibly additional infor$ation It is co$$on that the response to an in/uiry does not contain the display na$e of the responding device If the display na$e is needed, the in/uirer can trans$it a directed re/uest now that it knows the address of the responding device which will solicit the na$e as a further response  # device does not have to respond to an in/uiry re/uest It has a property setting called an *in/uiry scan* that controls whether or not it responds to such If the attribute is on, then it will respond to an in/uiry re/uest and if off, then it will not respond to such (hink of the phrase *in/uiry scan* as the devices choice as to whether it perfor$s the action of *scanning for in/uires* nce the two devices know each other's addresses, a connection can be for$ed between the$ through a process known as *paging* #gain, a device does not have to service a received connection re/uest It has a property setting called a *paging scan* which controls this If on, then a paging re/uest causes a new connection to be for$ed If off, it will not accept a new connection re/uest nce a connection is for$ed between the devices, that connection can be $aintained in a variety of states, the $ost co$$on being active However other states are available and are used to save power when there is no active co$$unication of data anticipated In order to per$it devices to co$$unicate with each other, there has to be an ele$ent of security involved !e usually don't want arbitrary devices to be able to connect with each other and share arbitrary infor$ation (o achieve this, a process called *bonding* is enacted +onding is achieved through the notion of *pairing* In pairing, the devices e4change their addresses, na$es and other data and generate keys that they share with each other Pairing Page 1,)

typically re/uires an e4plicit interaction fro$ the user to per$it the pairing to succeed (he user interaction can be as si$ple as *I approve this device* with a button click or it can be richer with the entry of a pass)code to authenticate and prove that one is who one clai$s to be (he +luetooth protocol provides support for different classes of power (his translates directly into the signal strength of the radio "e$e$ber that the $ore power used by the radio, the heavier the drain on the power source If the power source is batteries, the $ore power used to trans$it data, the shorter the life of the batteries  #t the lower levels, +luetooth takes care of e4changing data between partners However, there is $uch $ore to +luetooth than 6ust si$ple data e4change In order to provide interoperability between devices built by $ultiple $anufacturers, higher level protocols called *profiles* have been defined (hese profiles define *what* is trans$itted over +luetooth for a given device function o$e of the profiles we will co$e across include-

•

;)P L Head et Profile 8eg a +luetooth ear piece9

•

;P L Hands Free Profile 8eg +luetooth co$$unication in a car9

•

;=? L Hu$an Interface Eevice 8eg a keyboard or $ouse9

•

)PP L erial Port Profile

•

+2?P L #dvanced #udio Eistribution profile 8eg connection to +luetooth speakers9

•

+(:P L #udio Disual "e$ote ontrol Profile

5nowing that these protocols e4ist, it is not sufficient that two +luetooth devices are in range of each other, they $ust also both support the sa$e profile that is desired to be used  #t a higher level that the connection are the transport protocols available to us (hese include-

•

(:D L "adio Fre/uency o$$unications Protocol (his protocol provides a reliable strea$ oriented trans$ission :oosely, you can co$pare it to (P

•

A2:+P L :ogical :ink ontrol and #daption Protocol (his is a packet oriented protocol "FMM builds on :#P

•

+:A L #synchronous onnection oriented :ogical protocol :#P builds on #:

•

):D L Doice /uality audio protocol

(o allow $ultiple conversations to be processed in parallel, the concept of the *port* is introduced (his is si$ilar to a (P.IP port nu$ber :#P ports can be odd nu$bered values between 1 and 3=@= For "FMM, the port nu$bers are called channels and are between 1 and 30 In the +luetooth docu$entation, ports are referred to as *Protocol ervice Multiple4ers* or *PMs*

Page 1,,

ertain port nu$bers used by :#P are designated as reserved for well defined purposes

Bluetooth /,%%

(he Aeneric #ttribute Protocol 8strangely called A#((9 provides a $echanis$ for passing data in a standard for$ A#(( is always present in +: (hink of A#(( as a way to send and receive data that is *re$e$bered* at the A#(( server In addition, a client can re/uest the values of data ite$s as well as receiver asynchronous notifications as events when so$ething interesting happens  #t the high level of the protocol there is the concept of a service (he service is the grouping of functionally related attributes !ithin a service are characteristics where a characteristic is a property of that service ach characteristic type is identified by its own 77IE value In addition a characteristic contains a value, properties, security and $ay also include descriptors

ee also•

Aeneric #ttribute Profile 8A#((9

•

generic attributes 8gatt9 and the generic attribute profile

•

A#(()+ased specifications

•

A#(( services L #ssigned nu$bers

•

A#(( delarations L #ssigned nu$ber 

•

A#(( characteristics L #ssigned nu$bers

•

gatttool

Page 1,<

#er"ice &isco"ery 'rotocol

!hen a client application wishes to re/uest that a connection be established, the client needs to know the port nu$ber on which the server is listening In (P.IP land, this is achieved by having the client and the server share the i$plicit knowledge of the port nu$ber to use In +luetooth, e4tra functions have been $ade available pecifically, there is a service available called the ervice Eiscovery Protocol or *EP* #t the server, when a service is offered, the port nu$ber of that service is registered to the local EP !hen a client now wishes to use the target service, it first re/uests endpoint infor$ation fro$ the EP running on the server (he EP returns the endpoint infor$ation and the client now has all the infor$ation it needs to create a direct connection to the desired target service (he unit of infor$ation $anaged by the EP server is called a *service record* or *EP record*  # co$$and line interface tool called sdptool is available to e4a$ine a +luetooth device's EP data # si$ple co$$and is$ sdptool bro%se Bluetoot +ddressJ

(his returns a series of records of the for$-

•

ervice a$e

•

ervice Eescription

•

ervice Provider 

•

ervice "ecHandler 

•

ervice lass IE :ist

•

Protocol Eescriptor :ist

•

Profile Eescriptor :ist

•

:anguage +ase #ttr :ist

ee also•

$an819 L sdptool

"luetooth ) Programming !ithin the  . :inu4 environ$ent we have an i$ple$entation of the #PI stack called *+lueG* (he +lueG i$ple$entation supports "FMM, :#P,  and HI

In order to perfor$ +luetooth progra$$ing we $ust install the package called *libbluetooth) dev* using$ sudo apt-get i&stall libbluetoot-de/

!hen co$piling, we need to link with libbluetooth ee also•

 #n Introduction to +luetooth Progra$$ing

Page 1,9

hci1get1route

"etrieve a handle to the specified +luetooth device or the first available if 7:: is supplied i&t ci7get7route.bdaddr7t Rbdaddr

hci1open1de"

pen the specified device and get a handle to that device (he returned value is a socket i&t ci7ope&7de/.i&t de/7id

If the return is )1 then an error was encountered and the details of the error can be found in err&o hci1inquiry i&t ci7i&Uuir,. i&t de/7id i&t le& i&t max7rsp co&st ui&tG7t Rlap i&Uuir,7i&fo RRii lo&g flags

where-

•

de/7id L the device id of the adapter as retruned by hciTgetTroute

•

le& L (he duration of the scan Z 1B seconds

•

max7rsp L (he $a4i$u$ nu$ber of responses we are willing to accept

•

lap L $ay be 7::

•

ii L Pointer to an array of in/uiryTinfo structures to be populated (he storage $ust e4ist and be at least of si%e max7rsp R siCeof.i&Uuir,7i&fo • flags ◦ 0 L ached results allowed ◦ =(EM7:+:;E7A8); L #ny cached values are discarded and only new responses will be used (he in/uiryTinfo is a struct containing-

•

bdaddrTt bdaddr 

•

uintBTt pscanTrepT$ode

•

uintBTt pscanTperiodT$ode

•

uintBTt pscanT$ode

Page 1<0

•

uintBTt devTclassO3 L (he device class is encoded in the assigned nu$bers L baseband

•

uint1@Tt clockToffset

ee also•

 #ssigned nu$bers L baseband

hci1read1remote1name

"etrieve the display na$e of a specified device i&t ci7read7remote7&ame. i&t ci7sock co&st baddr7t Raddr i&t le& car R&ame i&t timeout 

•

le& L the si%e of the na$e buffer to hold the display na$e

•

&ame L a buffer to hold the display na$e

•

timeout L Ma4i$u$ nu$ber of $illiseconds to wait before giving up

n return, a value of 0 indicates success

str(ba

onvert a string representation of a +luetooth address into an address str2ba.co&st car Rstr bdaddr7t Rba

!here str is the string representation of the +luetooth address and ba is a pointer to a bdaddr7t structure to hold the resulting address

ba(str

onvert a +luetooth address to a string (he string buffer $ust be at least 1B bytes long ba2str.co&st bdaddr7t Rba car Rstr

(he ba is a pointer to a bdaddr7t structure while str is the buffer to be populated with the string representation sdpTconnect89 sdpTserviceTsearchTattrTre/89

Page 1<1

sdpTrecordTregister89

"luetooth (udio +luetooth speakers and headphones are co$$on so a natural /uestion would be how to get sound out of the$ fro$ the Pi (he answer is to install an application called Pulse#udio $ sudo apt-get i&stall pulseaudio pulseaudio-module-bluetoot

(he +luetooth profile we want to work with is called #EP 8#dvanced #udio Eistribution Profile9

"luetooth F)O##  # serial protocol is available via +luetooth and is called *"FMM* for *"adio Fre/uency o$$unication*

!hen progra$$ing with , we want to create a socket usingi&t s 9 socket.+7BA8E*DD*; )D:N7)*(E+ B*P(D*D7(:DY

 # socket address structure for +luetooth "FMM is a struct called sockaddr7rc which contains-

•

sa7famil, rc7famil, L (his will always be +7BA8E*DD*;

•

bdaddr7t rc7bdaddr L (he address of the device to which we wish to connect or listen upon If any local +luetooth adapter will suffice when we are a server, we can supply B?+??(7+>L

•

ui&tG7t rc7ca&&el L (he channel to which we wish to connect

(o be a client of an "FMM server, we would useFi&clude Fi&clude Fi&clude Fi&clude Fi&clude

stdio5J u&istd5J s,ssocket5J bluetootbluetoot5J bluetootrfcomm5J

i&t mai&.i&t argc car Rarg/ST  if .argc K9 2  pri&tf."8sage s bdaddr^&" arg/S0TY retur& 0Y  struct sockaddr7rc addr 9 0Y i&t s statusY car Rdest 9 arg/S1TY s 9 socket.+7BA8E*DD*; )D:N7)*(E+ B*P(D*D7(:DY addr5rc7famil, 9 +7BA8E*DD*;Y Page 1<2

addr5rc7ca&&el 9 1Y str2ba.dest addr5rc7bdaddrY status 9 co&&ect.s.struct sockaddr Raddr siCeof.addr Y if.status 99 0  status 9 se&d.s "elloK" H 0Y  if.status  0    perror."co&&ect"Y    close.sY retur& 0Y 

while to be a server we would useFi&clude Fi&clude Fi&clude Fi&clude Fi&clude

stdio5J u&istd5J s,ssocket5J bluetootbluetoot5J bluetootrfcomm5J

i&t mai&.i&t argc car RRarg/  struct sockaddr7rc loc7addr 9  0  rem7addr 9  0 Y car bufS1024T 9  0 Y i&t s clie&t b,tes7readY sockle&7t opt 9 siCeof.rem7addrY  allocate socket s 9 socket.+7BA8E*DD*; )D:N7)*(E+ B*P(D*D7(:DY  bi&d socket to port 1 of te first a/ailable  local bluetoot adapter loc7addr5rc7famil, 9 +7BA8E*DD*;Y loc7addr5rc7bdaddr 9 RB?+??(7+>LY loc7addr5rc7ca&&el 9 .ui&tG7t 1Y bi&d.s .struct sockaddr Rloc7addr siCeof.loc7addrY  put socket i&to liste&i&g mode liste&.s 1Y  accept o&e co&&ectio& clie&t 9 accept.s .struct sockaddr Rrem7addr optY ba2str.rem7addr5rc7bdaddr bufY fpri&tf.stderr "accepted co&&ectio& from s^&" bufY memset.buf 0 siCeof.bufY  read data from te clie&t b,tes7read 9 read.clie&t buf siCeof.bufY if .b,tes7read J 0  pri&tf."recei/ed SsT^&" bufY     

 close co&&ectio& close.clie&tY close.sY

Page 1
retur& 0Y 

ee also•

"FMM with ( 0=10

•

$an819 L rfco$$

•

 #n Introduction to +luetooth Progra$$ing

"luetooth tools l(ping

In (P.IP networking, we have a tool called ping which sends an IMP packet over the network to which the partner responds !e can use this co$$and to deter$ine the *liveness* of the partner as well as get the round trip response ti$es For +luetooth, we have a si$ilar tool called * l2pi&g* (his co$$and sends a :#P echo re/uest to the partner and waits for the response  #t the highest level, we use$ sudo l2pi&g bd7addrJ

where bdTaddr is the address of the target device Here is an e4a$ple output$ sudo l2pi&g 001+6??+6113 Pi&g 001+6??+6113 from BG26EBH203# .data siCe 44 555 44 b,tes from 001+6??+6113 id 0 time 11532ms 44 b,tes from 001+6??+6113 id 1 time HH50Hms 44 b,tes from 001+6??+6113 id 2 time 1#5G4ms 44 b,tes from 001+6??+6113 id 3 time !253Gms

 #s of 02.01@, running the l2pi&g co$$and on current "aspbian ends after about 2 seconds of pinging with a $essage)e&d failed :o&&ectio& reset b, peer

urrent thinking is that this is caused by a deliberate kernel ti$eout of :#P re/uests that don't result in a connection (he theory believed to be that to save battery life in real +luetooth devices, if a connection isn't established in the ti$eout period, don't bother to keep trying and, presu$ably, waste power resources (he lping co$$and is delivered as part of the * blueC* package ee also•

$an819 L lping

rfcomm

ee also•

Page 1<

$an819 L rfco$$

bluetoothctl

ne of the pri$ary tools for working with +luetooth is called bluetoothctl ddly, this co$$and see$s to have only the bare bones of a $an page 8sha$e9 ne should run bluetootctl as root using$ sudo bluetootctl

If you fail to run it as root, it will 6ust silently sit there until you interrupt it (his co$$and line tool has the following co$$ands-

•

list L :ist available controllers

•

so% SctrlT L ontroller infor$ation

•

select ctrlJ L elect default controller 

•

de/ices L :ist available devices

•

paired-de/ices L :ist paired devices

•

po%er o&offJ L et controller power 

•

pairable o&offJ L et controller pairable $ode

•

disco/erable o&offJ L et controller discoverable $ode

•

age&t o&offcapabilit,J L nable.disable agent with given capability

•

default-age&t L et agent as the default one

•

sca& o&offJ L can for devices

•

i&fo de/J L Eevice infor$ation

•

pair de/J L Pair with device

•

trust de/J L (rust device

•

u&trust de/J L 7ntrust device

•

block de/J L +lock device

•

u&block de/J L 7nblock device

•

remo/e de/J L "e$ove device

•

co&&ect de/J L onnect device

•

disco&&ect de/J L Eisconnect device

•

/ersio& L Eisplay version

•

Uuit L Uuit progra$

ee also-

Page 1<$

hciconfig

 #s $entioned, HI is the *Host)ontroller Interface* which is the layer of co$$unication between the higher level protocols of +luetooth and the +luetooth lower level controller (he *cico&fig* co$$and allows us to e4ecute co$$ands through this logical interface "unning cico&fig by itself will list all the +luetooth devices found on the co$puter$ cico&fig ci0 *,pe B(E?( Bus 8+(* B? +ddress BG26EBH203# +:A *8 1021G ):D *8 H41 8P (8>>=>< P):+> (@ b,tes1#100 acl1!0 sco0 e/e&ts4!6 errors0 *@ b,tes6#!2 acl1!0 sco0 comma&ds1G4 errors0

ach +luetooth device has a logical identifier of the for$ * ci@* where the devices are nu$bered 0, 1,  M etc (o refer to a specific device, $ost of the co$$ands that we issue through hciconfig will take the hciJ device identifier to target the correct instance o$e of the $ore interesting co$$ands we can perfor$ with hciconfig include-

•

Aetting and setting the devices display na$e property

•

nabling.disabling page support

•

nabling.disabling scan in/uiry support

(he hciconfig co$$and is supplied as part of the *blue%* package ee also•

$an8B9 L hciconfig

hcitool

(he hcitool is delivered as part of the * blueC* package (o scan for +luetooth : devices, use$ sudo citool lesca&

ee also•

$an819 L hcitool

gatttool

Interact with a +: device at the A#(( level In order to interact with a +: device at the gatt level, we need its device address 7sing *ictool lesca&* is a good way to get the address (ypically the progra$ is run with$ sudo gatttool --de/ice9+ddressJ --i&teracti/e

(his will return a co$$and pro$pt that starts with the partner device address-

Page 1<)

S4!1#14G0TSAETJ

(he subco$$ands available to us includeco&&ect disco&&ect primar, i&cluded caracteristics car-desc car-read-&d

Saddress Saddress t,peTT S88=?T Sstart &d Se&d &dTT Sstart &d Se&d &d S88=?TTT Sstart &dT Se&d &dT a&dleJ

car-read-uuid 88=?J Sstart car-%rite-reU a&dleJ &e% car-%rite-cmd a&dleJ &e% sec-le/el Slo% | medium mtu /alueJ

&dT Se&d &dT /alueJ /alueJ | igT

:o&&ect to a remote de/ice ?isco&&ect from a remote de/ice Primar, )er/ice ?isco/er, i&d =&cluded )er/ices :aracteristics ?isco/er, :aracteristics ?escriptor ?isco/er, :aracteristics alue?escriptor (ead b, a&dle :aracteristics alue?escriptor (ead b, 88=? :aracteristic alue 'rite .'rite (eUuest :aracteristic alue 'rite .>o respo&se )et securit, le/el5 ?efault lo% Exca&ge *8 for <+**+**

nce connected, we can interrogate the device about its pri$ary function by running the *pri$ary* co$$andS4!1#14G0TSAETJ attr a&dle 0x0001 e&d attr a&dle 0x000H e&d attr a&dle 0x000# e&d attr a&dle 0x000c e&d

primar, grp a&dle grp a&dle grp a&dle grp a&dle

0x000! 0x000G 0x000b 0x000e

uuid uuid uuid uuid

00001G00-0000-1000-G000-00G0!f#b34fb 00001G0f-0000-1000-G000-00G0!f#b34fb 00001G02-0000-1000-G000-00G0!f#b34fb 0000ffe0-0000-1000-G000-00G0!f#b34fb

otice specifically the 77IEs (hese correspond to the assigned nu$bers of the A#(( specifications ontrast this with the output of *bluetoothctl info* which shows the followingSbluetootTF i&fo 4!1#14G0 ?e/ice 4!1#14G0 +lias --4!-1#-14-G0 +ppeara&ce 0x03c1 =co& i&put-ke,board Paired &o *rusted &o Blocked &o :o&&ected ,es Aegac,Pairi&g &o 88=?
.00001G00-0000-1000-G000-00G0!f#b34fb .00001G02-0000-1000-G000-00G0!f#b34fb .00001G0f-0000-1000-G000-00G0!f#b34fb .0000ffe0-0000-1000-G000-00G0!f#b34fb

For e4a$ple, 041B0& is the I$$ediate #lert service :ooking back at the gatttool output, for each of the services, we see a *handle range* (his describes the handles to the characteristics offered by that service Fro$ the handles, we can ask the device what characteristics these representS4!1#14G0TSAETJ car-desc 0x000# 0x000b a&dle 0x000# uuid 00002G00-0000-1000-G000-00G0!f#b34fb a&dle 0x000a uuid 00002G03-0000-1000-G000-00G0!f#b34fb a&dle 0x000b uuid 00002a0H-0000-1000-G000-00G0!f#b34fb

(he 77IEs of the declarations and characteristics can then be e4a$ine in the assigned) nu$bers lists For e4a$ple Page 1<,

•

04B00& is

•

04B03 &

•

04#0@ ) #lert :evel

ee also•

+luetooth A#((

•

$an819 L gatttool

*icro %!hile HIP doesn't co$e supplied with a Micro E card reader, a board is available to add one (he board is called *(%at%iki* and is available fro$ hip Eip hop-

ee also•

(%at%iki Micro E reader 

Hardware interfacing e)amples n our e4pensive Ps, we don't readily have that lu4ury of interfacing with hardware and if.when we get it wrong, we will be unhappy that our our P is left a s$oking ruin !ith a cheap HIP, we are released fro$ the concern and fear that $ay inhibit us fro$ taking such risks #s such, we want to look into interfacing our HIPs with the huge nu$ber of electronic co$ponents out there to create new and interesting pro6ects and solutions (he following sections provide illustrations on how to connect electronics to our HIP and then show us a variety of software techni/ues to drive and interact with the$ ince the HIP supports a rich set of progra$$ing language choices, rather than pick 6ust one language, we will show interaction through a variety of languages If you only care about one language, then read the corresponding language specific recipes and discussions However, this $ay be an opportunity to co$pare the language you are fa$iliar with against another language since each of the progra$s perfor$s e4actly the sa$e function & you $ay be able to use Page 1<<

these language co$parisons as a "osetta stone to provide insight into how different language features work !hen interacting with new co$ponents, stop and Aoogle the$ It is al$ost a certainty that so$eone, so$ewhere has atte$pted this task before In fact, it is as likely that $any folks have achieved your task in the past #s such, learn fro$ the$ Eon't re)invent the wheel !hen a $anufacturer releases a new co$ponent, they co$$only $ake available a docu$ent called the *data sheet* (hink of this as the specification, operations guide and instructions for using that co$ponent If it is $ore than a trivial device, then it will e4pect protocols and bit se/uences with associated ti$ings If you have a working knowledge of electronics including protocols such as PI, I and 7#"( and are able to write applications in , then the chances are high that you could start fro$ the data sheet and build your own drivers to $ake the co$ponent work (he /uestion I would pose to you though is why do that If you could 6ust lift and re)use a high level library that perfor$s the task why would you not 6ust do that Fortunately, such libraries are prolific o$e $ay be for the Pi and so$e $ay be for other M7s such as the popular #rduinos For non)Pi devices, you $ay have to port the code to the Pi before you can use it (his brings us to the topic of pen ource pro6ects (hese are source code pro6ects where the source is $ade publicly available and any associated licenses are very per$issive Nou can usually find an pen ource pro6ect that co$es close to $eeting your needs and you can start fro$ there pen ource benefits fro$ the notion of others contributing back (his $ay be in the for$ of i$prove$ents or enhance$ents to the code base or it $ay be in the for$ of i$prove$ents to the docu$entation 8if any9 If you start to use an pen ource pro6ect and find proble$s and fi4 the$, sub$it the$ back so that the ne4t person who walks your path $ay benefit fro$ the ti$e and invest$ent you yourself $ade !hen working on a pro6ect and it starts to co$e together, it is natural to feel proud of one's work However, I caution against the idea of thinking that your pen ource library is better than an e4isting pen ource library Instead, think about how you can i$prove what is already there as opposed to duplicating an e4isting effort because 8perhaps9 you disagree with one s$all aspect of such an e4isting pro6ect Eon't publish a new wheel 6ust because you can, it will confuse future pen ource users when they look for a functional area and find do%ens of the$ as opposed to 6ust one good one (he Aithub repository is an e4cellent place to find and work with pen ource pro6ects It is based upon the Ait source code control paradig$s and Ait is now available on all operating syste$s and built into the $a6ority of Integrated Eevelop$ent nviron$ents including clipse

%imple $PI+ +utput change ne of the si$plest interfaces is the ability to change the signal level on an output API fro$ low to high or high to low (his can be used to trigger all kinds of e4ternal devices such as switching on a si$ple :E or energi%ing a relay If perfor$ed in con6unction with toggling Page 1<9

other pins, one can even create co$ple4 signals across $ultiple pins that can recreate co$ple4 protocols such as I or PI  #fter we write our applications to test signal changes on output, we can deter$ine if everything is working in a nu$ber of fashions !e can attach a si$ple $eter or logic probe or get sophisticated and attach a signal analy%er However the si$plest $echanis$ is still the attach$ent of an :E with a resistor !hen the signal is high, the :E lights up !hen the signal is low, the :E re$ains dark !e can create a bit of a $ore sophisticated circuit which is a si$ple logic probe as follows-

In this circuit, if the input is high, the "ed :E 8:E19 will switch on and the Areen go dark, while if the input is low, the Areen :E 8:E9 will switch on and the "ed go dark If the input is open, then both :Es will be on  #s a breadboard layout, here is the sa$e circuit-

!ith this test circuit available to us, we are now at a place where we have an environ$ent in which to test si$ple signal changes !e will pick a API pin, attach our logic probe and Page 190

toggle the value periodically to watch it change .sing the hell If we assu$e that we are running on a CC 5ernel and that we have our probe attached to JI)P0, then a 1 signal on it will light the red led while a 0 signal will light the green led (o change the settings fro$ the shell, perfor$ the following$ F F F F F F

sudo bas cd s,sclassgpio eco "101H" J export cd gpio101H eco "out" J directio& eco "1" J /alue eco "0" J /alue

(he last two state$ents control the signal appearing upon the output # *1* written to the file called *value* causes the corresponding ter$inal to go high while a *0* written to the file causes the ter$inal to go low ee also•

API interfacing

.sing li!soc Here is an e4a$ple of using libsoc to toggle on and off @=D-P0 on a CC 5ernel using libsocFi&clude stdio5J Fi&clude stdlib5J Fi&clude libsoc7gpio5J i&t mai&.i&t argc car Rarg/ST  gpio Rm,gpio 9 libsoc7gpio7reUuest.101H A)7);+(E?Y if .m,gpio 99 >8AA  pri&tf."ailed to ope& gpio^&"Y retur& 0Y  libsoc7gpio7set7directio&.m,gpio D8*P8*Y i&t iY for .i90Y i10Y i]]  libsoc7gpio7set7le/el.m,gpio AD'Y   sleep.1Y libsoc7gpio7set7le/el.m,gpio ;=<;Y   sleep.1Y  pri&tf."+ll do&eK^&"Y retur& 0Y 

(he application $ust be linked with * -lsoc* ee also•

Page 191

API using libsoc

.sing 2ode-ED ode)"E provides a powerful co$ponent for controlling output signals and looks like this when added to the canvas-

ee also•

API with ode)"E

•

Nou(ube- HIP (utorials- API utput with ode)"E

%imple $PI+ Input change !e have looked at changing the output singal on a ter$inal, but what about sensing an input change Fortunately, we can do that as well !e created a si$ple switch based input as shown here with a pull)down resistor-

.sing li!soc Here is an e4a$ple of using libsoc to read the value fro$ @=D-P2 on a CC 5ernel using libsocFi&clude stdio5J Fi&clude stdlib5J Fi&clude libsoc7gpio5J i&t mai&.i&t argc car Rarg/ST  gpio Rm,gpio 9 libsoc7gpio7reUuest.101G R @=D-P2 R A)7);+(E?Y if .m,gpio 99 >8AA  pri&tf."ailed to ope& gpio^&"Y retur& 0Y Page 192

 

 libsoc7gpio7set7directio&.m,gpio =>P8*Y %ile.1  gpio7le/el /alue 9 libsoc7gpio7get7le/el.m,gpioY pri&tf."Ae/el 9 d^&" /alueY sleep.1Y  retur& 0Y



(he application $ust be linked with * -lsoc* !hen run, it prints the current signal level on the screen !hen we press the button, we see the level change !e can also register a callback function that will be invoked when an input I. change occursFi&clude stdio5J Fi&clude stdlib5J Fi&clude libsoc7gpio5J i&t m,:allback./oid Rdata  pri&tf."E/e&t callback^&"Y  i&t mai&.i&t argc car Rarg/ST  gpio Rm,gpio 9 libsoc7gpio7reUuest.101G R @=D-P2 R A)7);+(E?Y if .m,gpio 99 >8AA  pri&tf."ailed to ope& gpio^&"Y retur& 0Y  libsoc7gpio7set7directio&.m,gpio =>P8*Y libsoc7gpio7set7edge.m,gpio (=)=><Y libsoc7gpio7callback7i&terrupt.m,gpio m,:allback >8AAY   sleep.####Y retur& 0Y 

ee also•

API using libsoc

.sing 2ode-ED !ith the sa$e physical setup as described, we can write a ode)"E flow Here is what it looks like-

!e $onitor the input ter$inal called JI)P (his is polled and passed continuously down the line (he *hanged* node looks at a flow variable to see if the current value is the sa$e as the last seen value If it is ( 8ie it has changed9 then we propagate onwards to *ave latest* Here we save the new value read fro$ the input into the flow variable Finally we write a debug $essage to show that an input change was detected  #n even better solution is to use the ?ohnny)Five *+utton* capability (he ode)"E flow will Page 19/

look as follows-

while the i$ple$entation of the o&&,! node will contain/ar butto& 9 &e% fi/e5Butto&."@=D-P2"Y butto&5o&."up" fu&ctio&.  &ode5se&d.topic "butto&" pa,load falseY Y butto&5o&."do%&" fu&ctio&.  &ode5se&d.topic "butto&" pa,load trueY Y

ee also•

Nou(ube- HIP (utorials- API Input with ode)"E

$PI+ e)tenders  #lthough HIP already has e4posed API headers, there are always ti$es when you find yourself wanting $ore !e have the capability to e4pand the nu$ber of APIs available to us through so$e relatively ine4pensive integrated circuits

P)F789:  #n e4a$ple of an e4tender is called the PFB2=C (he PFB2=C can be found on e+ay for about C0 cents each

(his is an I device and hence works using only two wires 7sing this I we configure it with a 3 bit address 8000)1119 that is used to select the slave address of the device (here are B per$utations of 3 bits ince each address has B Is and we can have up to B devices, this $eans a potential total of @C additional pins (he PFB2=C# is the sa$e I but has a different set of I addresses If we $i4 PFB2=C and PFB2=C# devices, we can reach a total of 1B pins It appears that the device will use a pull)up resistor for a high and bring the pin to ground for low (his $eans that if we want to use any of the pins for input, we should set their write $ode to high first (his will allow either a high or low input signal to be detected It would appear that if we set the output signal to be low and then fed a raw high signal into the device, we would have a short ote that the output currents vary on signal For a low output, the typical current that can be drawn is 2$# while for a high level output, the $a4i$u$ current that can be drawn is 300u# ote that is $icro a$ps and not $illia$ps (his $eans that you can't drive a load high

Page 19

Here is the pin diagra$ for the device-

Here is a description of the pins(ymbol

Pin

Description

%0%2

14 24 /

%ddressing

P0P,

4 $4 )4 ,4 94 104 114 12

Bi directional IF3

I=T

1/

Interru!t out!ut

+C8

1

+erial Clock 8ine

+5%

1$

+erial 5ata 8ine

#55

1)

+u!!ly #oltage ?2.$# – )#@

#ss ?*round@

<

*round

(he address that the slave device can be found upon is configurable via the +0-+2 pins It appears at the following addressPFB2=C )

*

4

3

0

1

0

0

+

,

%2 %1

-

%0

PFB2=C# )

*

4

3

0

1

1

1

+

,

%2 %1

-

%0

(he pins +0-+2 $ust not float (his results in the following table-

Page 19$

+

,

-

ddress PC/*04

ddress PC/*04

0

0

0

020

0/<

0

0

1

021

0/9

0

1

0

022

0/a

0

1

1

02/

0/b

1

0

0

02

0/c

1

0

1

02$

0/d

1

1

0

02)

0/e

1

1

1

02,

0/

 

!e can build a sa$ple circuit that shows driving :Es-

 #nd on a breadboard-

Page 19)

ee also•

Eatasheet

#)P6;<=9 (he MP301= fro$ Microchip is a 1@ bit input.output port e4pander that uses the I interface (he going price for an instance of one of these on e+ay is about ;1 (he device has 1@ API pins that can be set as input or output controlled in two banks 8ports9 !e can read or write the values of one bank at a ti$e $eaning that if we want to write all 1@ bits, this would be two I operations and the sa$e for reading (he device is also capable of generating interrupts for input signal detection If we i$agine a 1005h% clock rate, then to switch a bit on or off 8and we can do these in groups of B9 then that would be 3 bytes of data plus acknowledg$ents & \30 bits & which would i$ply a $a4i$u$ switching rate of about 03$s

(he device operates on a volate of 33D or 2D (he pin interface is-

Page 19,

Pin

1abel

Description

1

*PB0

Bidirectional IF3

2

*BP1

Bidirectional IF3

/

*BP2

Bidirectional IF3



*BP/

Bidirectional IF3

$

*BP

Bidirectional IF3

)

*BP$

Bidirectional IF3

,

*BP)

Bidirectional IF3

<

*BP,

Bidirectional IF3

9

#55

Po"er ?/./#  $#@

10

#++

*round

11

=C

=ot connected

12

+C8

+erial clock in!ut

1/

+5%

+erial data in!utFout!ut

1

=C

=ot connected

1$

%0

%ddress !in

1)

%1

%ddress !in

1,

%2

%ddress !in

1<

'6+6T

Hard"are reset

19

I=TB

Interru!t out!ut or !ort B

20

I=T%

Interru!t out!ut or !ort %

21

*P%0

Bidirectional IF3

22

*P%1

Bidirectional IF3

2/

*P%2

Bidirectional IF3

2

*P%/

Bidirectional IF3

2$

*P%

Bidirectional IF3

2)

*P%$

Bidirectional IF3

2,

*P%)

Bidirectional IF3

2<

*P%,

Bidirectional IF3

(he I address of the device is = bits given by )

*

4

3

0

1

0

0

+

,

%2 %1

-

%0

 #nd hence has addresses in the range 0x20 L 0x26 (he register addresses are-

Page 19<

Re&ister address

Name

Description

000

I35I'%

5irection control or !ort %K • 1 – in!ut • 0 – out!ut

001

I35I'B

5irection control or !ort BK • 1 – in!ut • 0 – out!ut

002

IP38%

Polarity inersion or in!ut or !ort %K • 1 – inerted • 0 – asis

00/

IP38B

Polarity inersion or in!ut or !ort BK • 1 – inerted • 0 – asis

00

*PI=T6=%

Interru!t enable or a change or !ort %K • 1 – 6nable in!ut !in or interru!t on change eent • 0 – 5isable in!ut !in or interru!t on change eent

00$

*PI=T6=B

Interru!t enable or a change or !ort BK • 1 – 6nable in!ut !in or interru!t on change eent • 0 – 5isable in!ut !in or interru!t on change eent

00)

56-#%8%

5eault alues or interru!t change co!arison or !ort %.

00,

56-#%8B

5eault alues or interru!t change co!arison or !ort B.

00<

I=TC3=%

Interru!t control or !ort %K • 1 – Co!are the alue on the !in to the alue in 56-#%8% • 0 – Co!are the alue on the !in to its !reious alue

009

I=TC3=B

Interru!t control or !ort BK • 1 – Co!are the alue on the !in to the alue in 56-#%8B • 0 – Co!are the alue on the !in to its !reious alue

00a

I3C3=

+ae register as 00b 2it

1abel

Description

,

B%=&

'egister a!!ingK • 'egisters in banks • 'egisters seuential

)

:I''3'

Interru!t !in a!!ingK • 1 – I=T !ins connected • 0 – I=T !ins se!arate. I=T% is associated "ith  !ort % and I=TB is associated "ith !ort B

$

+63P

+euential o!eration odeK • 1 – +euential o!eration disabled • 0 – +euential o!eration enabled



5I++87

+le" rate control

/

H%6=

Hard"are address enable

2

35'

3!en drain out!ut or I=T

1

I=TP38

Polarity o I=T out!utK • 1 – %ctie high • 0 – %ctie lo"

0

=F%

=ot used. +et as 0.

00b

I3C3=

+ae register as 00a

00c

*PPU%

Pull u! control or Port %K • 1 – Pullu! ia a 100& resistor 

Page 199

•

0 – Pullu! disabled

00d

*PPUB

Pull u! control or Port BK • 1 – Pullu! ia a 100& resistor  • 0 – Pullu! disabled

00e

I=T-%

Interru!t lags or Port %K • 1 – Pin caused an interru!t • 0 – =o interru!t detected

00

I=T-B

Interru!t lags or Port BK • 1 – Pin caused an interru!t • 0 – =o interru!t detected

010

I=TC%P%

#alues o *PI3 "hen interru!t occurred on !ort %K • 1 – Pin "as high • 0 – Pin "as lo"

011

I=TC%PB

#alues o *PI3 "hen interru!t occurred on !ort BK • 1 – Pin "as high • 0 – Pin "as lo"

012

*PI3%

'ead – 'eads the alues on !ort %

01/

*PI3B

'ead – 'eads the alues on !ort B

01

38%T%

01$

38%TB

ee also•

Eata sheet

,eoPi)els 2eoPi>el theory eoPi4els are :Es that are driven by a single data line of high speed signaling Most eoPi4els have a Kve and ground voltage source as well as a data line for input and a data line for output (he output of one eoPi4el can be fed into the input of the ne4t one to produce a string of such :Es (he input data to the :E is a strea$ of C bits of encoded data which should be interpreted as B bits for the red channel, B bits for the green channel and B bits for the blue channel ach channel can thus have a lu$inance value of between 0 and 22 +y $i4ing the values for each of the channels together, you can color an :E to any color you $ay choose #fter sending in a strea$ of C bits, if we send in a second strea$ of C bits /uickly after the first strea$, the second strea$ is *pushed* through to the ne4t :E in the chain (his can be repeated as far as desired If we pause sending in data, the current values are *latched* into place and each :E the$ re$e$bers its own value

(he ti$ings of the data signals for these :Es can be /uite tricky but fortunately great $inds have already built fantastic libraries for driving the$ correctly so we need not concern ourselves with these low level ti$ings and can instead concentrate on devising interesting pro6ects and purposes to which the :Es can be placed (here are a nu$ber of different types of these :Es with the $ost co$$on ones being known as !B11, !B1 or P:
eoPi4els are usually 2D devices but check the specs carefully ince eoPi4els draw a lot of current 8@0$# each9, do not try and power the$ fro$ low current sources Nou also need to be careful when sending signals into the$ and getting their polarity correct If you $ess up, they are unforgiving I reco$$end buying $ore instances that you will need in case you $ake a $istake

(he eight piece strip is labeled ?M7)B1)B It has C pins at each end of the strip labeled1abel

Description

Color

*=5

*round.

Gello"

5I=F53UT

3ne side is 5I= the other 53UT M this eans that the stri! is !olari;ed. These are the control data in!ut and out!ut lines.

*reen

,#5C

+ource oltage.

*=5

*round.

'ed Gello"

(he data is sent as C bits in Areen."ed.+lue order 8A"+9 ote that this is ( "A+ (he for$at of the data uses G" 8on)return)to)%ero9 encoding pecifically, the logic 0 and logic 1s are encoded as following

+oth bits correspond to a transition fro$ high to low to high again but the duration at which they are held indicates the encoding of a 1 or 0 (he data send to an individual device is C bits corresponding to B bits of color data for each of the "A+ co$ponents (he B bits identify the brightness of each of the channels with 1 being lowest and 22 being brightest Darious diagra$s show the ti$ing as follows-

Page 201

Darious data sheets show different ti$ing values in $icro secondss econdsDeice

-H

-1

-

,H

,1

,

7+2<11

0.$

2.0

2.$

1.2

1./

2.$

7+2<12

0./$

0.<

1.1$

0.,

0.)

1./

7+2<12B

0.

0.<$

1.2$

0.<

0.$

1.2$

P89<2/

0./$

1./)

1.,1

1./)

0./$

1.,1

 #s we see, for a !B1+, the *width* of a bit is about 12 $icroseconds For a full pi4el, this would be C bits or 30 $icroseconds (hinking of it another way way,, that would would be over 33,000 pi4els that could be updated per second For testing circuits, I like to use P:
ee also•

!B1 Eata heet

•

P:
•

7se a ;1 #((iny to drive addressable "A+ :Es

•

 #dafruit eoPi4el eoPi4el 7berguide

Page 202

2eoPi>els on )*+P (he ti$ings re/uired to operate eoPi4els natively on HIP are either not precise enough or because of the pre)e$tive nature of :inu4, not consistent enough #s such, the reco$$ended solution is to drive the$ through an inter$ediate such as an #t$el processor

2eoPi>els through the (rduino (he $ost accurate and deter$inistic way I know to drive eoPi4els fro$ HIP is to leverage the capability of an #rduino or #($ega chip ince there are e4cellent libraries available for the #rduino and the #rduino can handily drive the pi4els, p i4els, where we want to end up is HIP driving the #rduino which drives the eoPi4els :et us now drill into that to see how it will all work First we should always validate validate that we understand the core principles principles tart "ith an %rduino and the =eoPiel libraries and alidate that you can light the correctly. correctly. +ee the ollo"ing diagra. In this ea!le "e are using using %rduino %rduino  !in 5) as the data !in. =ote that "e hae a coon ground bet"een the %rduino and the =eoPiels.

The %daruit =eoPiel library is one o the libraries t hat is integrated into the 8ibrary :anager and can be installed uickly ro thereK

Page 20/

The sa!le I recoend to run coes ro the -ile J 6a!les J %daruit %daruit =eoPiel J strandtest. 6dit the ile to change the nuber o !iels in your strand ?do"n to one i needed@.

(he high level operation of the library is that you create an instance of the class+dafruit7>eoPixel strip 9 +dafruit7>eoPixel.&umPixels dataPi& >ED7(ED7N;OG00Y

!ith a variable now referencing an instance of the class, we can initiali%e the environ$ent withstrip5begi&.Y

allingstrip5so%.Y

(ransfers the internal $odel of what values each pi4el should have to the correct pi4el ow we can set the value of a pi4el with a call tostrip5setPixel:olor.pixel colorY

(he color value is a 3 bit integer with the the values set for red, green and blue If you know the e4act "A+ code you want, you can invokestrip5:olor.red gree& blue

which will return an encoded value  #dditional functions include setBrigt&ess. to scale the overall brightness of the devices, &umPixels. to return the nu$ber of pi4els we have defined, and getPixel. which will retrieve the current value of a specific pi4el ince the #rduino is capable of driving eoPi4els, how then does that apply to our Pi story (he answer is that we can use the #rduino as the driver of the eoPi4els and the HIP can drive the #rduino ince the cost of a si$ple #rduino ano is only a few dollars, this isn't a great issue Here is a sche$atic that illustrates an #rduino being driven by a HIP using IIPage 20

Here is an e4a$ple construction of this sche$atic-

!hen the circuits are wired together between the HIP and #rduino, a /uick check can be $ade using the ic detection tool which will list a device at address 0x10$ i2cdetect -, 1 0 1 2 3 4 00 -- -10 10 -- -- -- -20 -- -- -- -- -30 -- -- -- -- -40 -- -- -- -- -!0 -- -- -- -- -H0 -- -- -- -- -60 -- -- -- -- --

! ---------

H ---------

6 ---------

G --------

# --------

a --------

b --------

c --------

d --------

e --------

f --------

(he #rduino receives its instructions via an I connection # suitable #rduino sketch would beRR  R (ecei/e data o/er te =2: data bus a&d use tat data to dri/e a& attaced stri&g of >eoPixels5  R *e &otio& ere is tat %e %ill be co&&ected to a :8 tat for o&e reaso& or a&oter ca&Wt  R dri/e >eoPixels directl,5 +& example of tis %ould %ould be te (aspberr, Pi %ic does&Wt a/e  R te .eas, &o&-preemtable co&trol to dri/e at te timi&gs reUuired5  R R ?esig& >otes  R *e +rdui&o =2: i&terface does&Wt a&dle buffers J 32 b,tes5 +s suc %e ca&Wt simpl,  R recei/e a "lo&g stri&g" of data a&d i&stead a/e to break it do%& i&to a& arra, of  R commu&icatio&s5  R R *e data format expected is  R S 2 T - 2 b,tes of &umber of >eoPixels i& te stream stream i& &et%ork b,te order5  R S 3 TR - 3 b,tes of (ed
Page 20$

 R tra&slated i&to i&structio&s to dri/er te >eoPixels5 'e are assumi&g tat te u&it of data  R is te b,te a&d e&ce a/e to process o&e i&comi&g b,te at a time5 Because data bei&g processed  R is R>D*R i& si&gle b,te cu&ks %e a/e to mai&tai& a state maci&e i& order to k&o% "%ere %e  R are" as te b,tes arri/e5 'e defi&e te follo%i&g states  R R R )*+(* - 'aiti&g for te start data %ic is te le> of te &eopixel data to come5  R R P=@EA7(E? - 'aiti&g for te b,te for red ca&&el of te curre&t pixel5  R R P=@EA7<(EE> - 'aiti&g for te bt,e for te blue ca&&el of te curre&t pixel5  R R P=@EA7BA8E - 'aiti&g for te b,te for te gree& ca&&el of te curre&t pixel5  R R *e tra&sitio&s are simple  R R )*+(* -J P=@EA7(E? -J P=@EA7<(EE> -J P=@EA7BA8E R || -J )*+(* - =f %e a/e recei/ed all te pixel data %e expected  R || -J P=@EA7(E? - =f %e a/e more pixels to process  R R 300 pixels 9 300 R 3 b,tes 9 #00 b,tesY  R R Vautor >eil Nolba& .kolba&1Vkolba&5com  R Vdate 201H-06-11  R Fi&clude +dafruit7>eoPixel5J Fi&clude 'ire5J Fdefi&e ?EB8< 1 e&um )*+*E    )*+(* P=@EA7(E? P=@EA7<(EE> P=@EA7BA8E  stateY Fdefi&e ?E=:E7+??(E)) .0x10 static u&sig&ed sort &umPixels 9 0Y  *e &umber of pixels i& te stri&g5 static u&sig&ed sort curre&tPixel 9 0Y  *e curre&t pixel %e are populati&g %it data static +dafruit7>eoPixel stripY  *e >eoPixel dri/er static b,te co&figured 9 0Y  'eter or &ot te >eoPixel a&dler as bee& i&itialiCed5 static u&sig&ed sort le>ProcessedY  *e &umber of b,tes of start le> processed static u&sig&ed car red gree& blueY  *e ca&&els for te curre&t pixel5 static u&sig&ed lo&g last(ead*imeY  *ime of last read Fdefi&e AE?7P=> .13 static u&sig&ed car started 9 0Y  ;a/e %e started recei/i&g data` static )tri&g eaderBuffer 9 ""Y  Buffer of eader data before %e are "started"5 /oid i2c7recei/e;a&dler.i&t &umB,tes  for .Y &umB,tesJ0Y &umB,tes--    processB,te.'ire5read.Y    E&d of i2c7receic/e;a&dler /oid i2c7reUuest;a&dler.  Fifdef ?EB8< )erial5pri&t.."i2c7reUuest;a&dler - 'e &eed to retur& some data^&"Y Fe&dif 'ire5%rite.0x##Y   e&d of i2c7reUuest;a&dler RR  R =&itialiCe te state of te e&/iro&me&t for te )*+(* state5  R /oid set)tart.  Fifdef ?EB8< )erial5pri&tl&.."E&tered state )*+(*"Y Fe&dif state 9 )*+(*Y le>Processed 9 0Y &umPixels 9 0Y   E&d of set)tart RR  R Process o&e b,te of data recei/ed for processi&g5  R /oid processB,te.u&sig&ed car b,te 

Page 20)

 =f %e a/e &ot see& a b,te i& o/er a seco&d te& someti&g as go&e %ro&g  a&d let us assume tat %e are restarti&g our state5 if ..millis. - last(ead*ime J 1000    set)tart.Y  last(ead*ime 9 millis.Y R Fifdef ?EB8< )erial5pri&t.."'e got a b,te troug =2: "Y )erial5pri&tl&.b,te ;E@Y Fe&dif R if .state 99 )*+(*  &umPixels 9 .&umPixels G ] b,teY   le>Processed]]Y if .le>Processed 99 siCeof.&umPixels  Fifdef ?EB8< )erial5pri&t.."*e &umber of pixels follo%i&g is "Y   )erial5pri&tl&.&umPixelsY Fe&dif if .Kco&figured  strip 9 +dafruit7>eoPixel.&umPixels H >ED7<(B ] >ED7N;OG00Y if .strip5&umPixels. 99 0  )erial5pri&tl&.."ailed to create strip"Y   retur&Y  co&figured 9 1Y   strip5begi&.Y   E&d of K co&figured state 9 P=@EA7(E?Y curre&tPixel 9 0Y   E&d of got our le> 555  else if .state 99 P=@EA7(E?  red 9 b,teY state 9 P=@EA7<(EE>Y  else if .state 99 P=@EA7<(EE>  gree& 9 b,teY state 9 P=@EA7BA8EY  else if .state 99 P=@EA7BA8E  blue 9 b,teY state 9 P=@EA7(E?Y strip5setPixel:olor.curre&tPixel strip5:olor.red gree& blueY   curre&tPixel]]Y if .curre&tPixel 99 &umPixels  strip5so%.Y   set)tart.Y     E&d of processB,te /oid setup.  last(ead*ime 9 millis.Y   )erial5begi&.11!200Y   set)tart.Y   'ire5begi&.?E=:E7+??(E))Y   'ire5o&(ecei/e.i2c7recei/e;a&dlerY   'ire5o&(eUuest.i2c7reUuest;a&dlerY Fifdef ?EB8< )erial5pri&tl&."(ead,K 'e are &o% able to start recei/i&g =2: data5"Y Fe&dif   E&d of setup /oid serialE/e&t.  if .started  %ile.)erial5a/ailable.  u&sig&ed car i&:ar 9 )erial5read.Y   processB,te.i&:arY    E&d of started   E&d of serialE/e&t /oid loop.  if .Kstarted 

Page 20,

i&t c 9 )erial5read.Y if .c K9 -1   %e got a b,te eaderBuffer ]9 .carcY if .c 99 W^&W  if .eaderBuffer5starts'it."FFF>EDP=@EA?(=E(FFF"  )erial5pri&tl&."'E )+' *;E )*+(*KKKK"Y digital'rite.AE?7P=> ;=<;Y started 9 1Y  else  eaderBuffer 9 ""Y     )erial5%rite.cY   )erial5pri&tl&.eaderBufferY   E&d of %e got a b,te   E&d of Kstarted   E&d of loop

!hile this circuit and progra$ frag$ent work and sound great in theory, the practice actually left a lot to be desired I found that there were rando$ errors between the HIP and #rduino over the I bus (hese $ay have been able to be eli$inated with shorter cables but all in all, it wasn't satisfactory (hinking further, it dawned on $e that both HIP and the #druino have serial buses 87#"(9 Aiven that we want to send a $a4 of 300 pi4els which e/uals 300Z3 bytes which e/uals 300Z3ZB bits M end up with \=00 bits to color all the pi4els If we choose a bit rate of 11200 that should give us a $a4 of about 1 co$plete refreshes a second which is far $ore than we desire M so fro$ a speed perspective, we are fine (he circuit for serial processing is even si$pler than that for I-

ee also•

 #dafruit- eoPi4el uberguide

•

Aithub- adafruit.#dafruitTeoPi4el

Page 20<

2eoPi>els through 2ode34s?5ohnny-Five?(rduino +6) !ackpack  #fter writing the previous section, it was brought $y attention that a significant a$ount of work on this techni/ue had already been done and done far better than any effort I $ay have undertaken # Aithub pro6ect called *a6fisher.node)pi4el* had been i$ple$ented that uses an  #rduino as a ?ohnny)Five accessible *backpack*

(o prepare the #rduino for use as a eoPi4el back)pack, we $ust install the #rduino sketch provided as part of the solution First we clone the node)pi4el Aithub pro6ect Fro$ there, we will find a directory called fir$ware.build.backpack In that directory we will find the sketch called *backpack5i&o* !e should open this sketch in our #rduino IE, co$pile it and deploy it to our #rduino ano instance If you are using the sche$atic above, the way to load the #rduino is to detach it fro$ the circuit, progra$ it using a 7+ connector and then disconnect it fro$ the 7+ and attach it back to the circuit Eo not try and power it fro$ both Page 209

the HIP 2D output and the 7+ I don't know what would happen if you tried but I doubt it would be good at all If all has gone well, when we run * i2cdetect*, we should see the e4istence of the #rduino at address 0x42$ sudo 0 00 10 -20 -30 -40 -!0 -H0 -60 --

i2cdetect -, 2 1 2 3 4 ! -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- 42 -- -- --- -- -- -- --- -- -- -- --- -- -- -- --

H ---------

6 ---------

G ---88 ----

# --------

a --------

b --------

c --------

d --------

e --------

f --------

(he node)pi4el package is well docu$ented at the Aithub ho$e page (his guide should be a cheat)sheet only and not a definitive (he high level of usage is that we initiali%e a new ?ohnny)Five board and when get an indication that the board is ready, we can start working with the eoPi4els (he notion of node)pi4el is that we have a *strip* of pi4els !hether they are physically arranged in a strip, circle or other co$bination is i$$aterial & we logically think of the$ as a strip ach pi4el has an ordinal within the strip starting at 0, 1,  & etc (o use node)pi4el, we ask for the construction of a strip ob6ect that $odels the eoPi4el strip (his has a nu$ber of constructor  properties but for our purposes 8when using an #rduino +ackpack9 we care about-

•

board L the ?ohnny)Five board ob6ect

•

co&troller L Indicate that we want to use an #rduino as a backpack 7se *=2:B+:NP+:N*

•

bus L (he I bus on which the #rduino is attached For HIP use 

•

strips L #n array of integers where each integer represents the nu$ber of :Es on the corresponding pin off the #rduino For e4a$ple, an array of O, 3, 0, 1 would say that there are  :Es attached to Pin 0, 3 attached to pin 1, none attached to pin  and one attached to pin 3 # co$$on usage $ight be S00000010T which would say that we have 10 eoPi4els attached to #rduino pin @

For e4a$ple/ar pixel 9 reUuire."&ode-pixel"Y /ar strip 9 &e% pixel5)trip. board Io&&,i/eBoard co&troller "=2:B+:NP+:N" bus 2 strips S00000010T Y

!hen we ask the strip to be created, we need to wait for its *ready* event to be published before we can use it For e4a$plestrip5o&."read," fu&ctio&.   strip is &o% read, for use 555 Page 210

Y

ow that we have a strip ob6ect, we can start to use it ince a strip is a $odel of an array of eoPi4els, we can work with any of those pi4els !e obtain a pi4el ob6ect that represents a pi4el by calling/ar pixel 9 strip5pixel.addressY

when *address* is the nu$eric address of the pi4els starting at 0 nce we have the corresponding pi4el ob6ect, we can invoke the color. $ethod upon it (his sets the color value which can be supplied in a nu$ber of for$ats including-

•

Frrggbb L # he4 code value for e4a$ple Fff0000

•

&ame L # color na$e & for e4a$ple *orange*

•

SrgbT L # color array

ote that setting a pi4el's color does not cause that pi4el to change color i$$ediately Instead we set the colors of all the pi4els we want to change and then invoke the * so%.* $ethod on the strip ob6ect (here are also so$e convenience functions available on strip including-

•

off. ) switches off all the pi4els

•

color.color)tri&g L set the color of all the pi4els to the given color string

 # si$ple application illustrating a test would be"use strict"Y /ar fi/e 9 reUuire.WIo&&,-fi/eWY /ar board7io 9 reUuire.Wcip-ioWY /ar pixel 9 reUuire."&ode-pixel"Y /ar board 9 &e% fi/e5Board. io &e% board7io. Y /ar colors 9 S"Fff0000" "F00ff00" "F0000ff"TY board5o&.Wread,W fu&ctio&.  let strip 9 &e% pixel5)trip. board tis co&troller "=2:B+:NP+:N" bus 2 strips S0000001T Y let i 9 0Y strip5o&."read," fu&ctio&.  co&sole5log.")trip read,K"Y set=&ter/al.fu&ctio&.  tr,  co&sole5log.")etti&g color " ] colorsSicolors5le>TY   strip5color.colorsSicolors5le>TY   strip5so%.Y   i]]Y  catc.err  co&sole5log.":augt a& error " ] errY 

Page 211

 1000Y Y strip5o&."error" fu&ctio&.  co&sole5log.")trip error detected"Y Y Y

(his app cycles between three colors ee also•

I o$ponent +ackpacks

•

Aithub- a6fisher.node)pi4el

•

?ohnny)Five

(C- dot matri) display – H-::;<= (hese are e4tre$ely cheap and popular 1@ colu$n by  row :E displays 8also known as the 1@09 bviously in that s$all space you can't show $uch but you can show enough for $any functions

(he device is a 2D device but since it is write only, we don't have to worry about level shifting (he device has a slew of wiring connections though and if one consults the data sheet, one will find a wealth of options

Page 212

Pin

Name

Description

1

*=5

*round

2

#55

+ource $# ?Oe@

/

#6 ?Contrast@



'+ ?'egister +elect@

'egister select • 1 – data in!ut • 0 – instruction in!ut

$

'F7

'eadF7rite • 1 – read • 0 – "rite

)

6nableF+trobe

+tarts data readF"rite. 5ata is clocked on the alling edge.

,

5B0

Used in
<

5B1

Used in
9

5B2

Used in
10

5B/

Used in
11

5B

Used in bit or
12

5B$

Used in bit or
1/

5B)

Used in bit or
1

5B,

Used in bit or
1$

Back 8edO

Back light 865 Oe

1)

Back 8ed

Back light 865 e

(he device has two banks of "#M ne is for display data and is called EE"#M while the other is for character generation and is called A"#M EE"#M is B0 bytes in si%e (he selection of which bank of "#M to be used is $ade by setting the () 8register select9 pin (he device can be used in either a C bit transfer $ode or an B bit transfer $ode In B bit $ode, all the pins labeled ?B0)?B6 are used In C bit $ode, only the pins labeled in ?B4)?B6 are used (o transfer B bits of data in C bit $ode, two transfers are re/uired (he order of data is the C high order bits in the first trans$ission and the C low order bits in the second trans$ission For two lines of display, take care to reali%e that the address of the 1st position on line two does not i$$ediately follow the last position on line 1

ddress

,

+

3

...

35

4-

8ine 1

000

001

002

...

02)

02,

8ine 2

00

01

02

...

0))

0),

Page 21/

(he co$bination of () and (' provide control infor$ationR(

R6"   Operation

0

0

Peror an internal o!eration.

0

1

'ead busy lag and address counter.

1

0

7rite data.

1

1

'ead data.

Instructions-

•

lear display

lears the display and sets the EE"#M address counter to 0

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

 0

0

0

0

0

0

0

0

0

•

D2-

1

"eturn ho$e

ets the EE"#M address counter to 0 #lso resets any display shifting that $ay be present

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

 0

0

0

0

0

0

0

0

1

•

D2-



ntry $ode properties

ets the address counter direction for auto)incre$ent or auto)decre$ent #lso specifies whether or not the display should be shifted

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 0

0

0

0

0

0

0

1

IF5

+

 # constant called A:?7E>*(LD?E)E* with a value of 0x04 $ay be used as a base ther related constants are-

•

:ET("N"IAH( Q 0400

•

:ET("N:F( Q 040

Page 21

•

:ET("NHIF(I"M( Q 0401

•

:ET("NHIF(E"M( Q 0400

•

Eisplay $ode properties

ets display controls

R(

R6"

D20

D2)

D2*

 0

0

0

0

0

D24

0

D23

D2+

1

5

D2,

C

D2-

B

◦ ontrols display visibility as a whole 8 ?9 ▪ 0 L off L A:?7?=)PA+LD ▪ 1 L on L A:?7?=)PA+LD> ◦ ontrols visibility of cursor 8 :9▪ 0 L off L A:?7:8()D(D ▪ 1 L on L A:?7:8()D(D> ◦ ontrols blinking state of cursor 8 B9 ▪ 0 L off L A:?7BA=>ND ▪ 1 L on L A:?7BA=>ND>  # constant called A:?7?=)PA+L:D>*(DA with a value of 0x0G $ay be used as a base ther related constants are-

•

:ETEIP:#N Q 040C

•

:ETEIP:#NFF Q 0400

•

:ET7"" Q 040

•

:ET7""FF Q 0400

•

:ET+:I5 Q 0401

•

:ET+:I5FF Q 0400

•

ursor or display shift

R(

R6"

D20

D2)

D2*

D24

D23

D2+

 0

0

0

0

0

1

+FC

'F8

•

Page 21$

Function Mode properties

D2,



D2-



R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 0

0

0

0

1

58

=

-





◦ Eata length 8C or B bit9 8 ?A9 ▪ 0 L Cbits L A:?74B=*D?E ▪ 1 L Bbits L A:?7GB=*D?E ◦ u$ber of lines to display 8 >9 ▪ 0 L 1 line L A:?71A=>E ▪ 1 L  lines L A:?72A=>E ◦ haracter font 89 ▪ 0 L 24B dots L A:?7!xG?D*) ▪ 1 L 2410 dots L A:?7!x10?D*)  # constant called A:?78>:*=D>)E* with a value of 0x20 $ay be used as a base ther related constants are-

•

:ETB+I(ME Q 0410

•

:ETC+I(ME Q 0400

•

:ET:I

Q 040B

•

:ET1:I

Q 0400

•

:ET2410E( Q 040C

•

:ET24BE( Q 0400

•

et A"#M address

et the address counter 8#9 for A"#M

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 0

0

0

1

%C$

%C

%C/

%C2

%C1

%C0

•

et EE"#M address

et the address counter 8#9 for EE"#M

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 0

0

1

%C)

%C$

%C

%C/

%C2

%C1

%C0

Page 21)

•

"ead busy flag and address

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 0

1

B-

%C)

%C$

%C

%C/

%C2

%C1

%C0

 #lways check the busy flag 8+F9 to deter$ine if the device is busy before perfor$ing an operation

•

!rite data to "#M

!rites data to either A"#M or EE"#M (he choice of whether A"#M or EE"#M is written is based on the last previous address change of the address counter For e4a$ple, if the address counter for EE"#M was last set, then the ne4t write will be to EE"#M

R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 1

0

5,

5)

5$

5

5/

52

51

50

 #fter a write to "#M, the address is auto$atically incre$ented in preparation for the ne4t write operation

•

"ead data fro$ "#M

"eads data fro$ either A"#M or EE"#M (he choice of whether A"#M or EE"#M is read is based on the previous address change of the address counter For e4a$ple, if the address counter for EE"#M was last set, then the ne4t read will be fro$ EE"#M R(

R6"

D20

D2)

D2*

D24

D23

D2+

D2,

D2-

 1

1

5,

5)

5$

5

5/

52

51

50

 #fter a read fro$ "#M, the address is auto$atically incre$ented in preparation for the ne4t write operation haracter table

Page 21,

0000

0001

0010

0000

0011

0100

0101

0111

1000

0

]

P

^

p

0001

>

1

#

U

a

/

0010

*



+

"

b

r

0011

V

3





c

s

0100

;

C

E

(

d

t

0101



2



7

e

u

0110

_

@

F

D

f

v

0111

'

=

A

!

g

e

1000

8

B

H

J

h

4

1001

9

<

I

N

i

y

1010

Z

-

?

G

6

%

1011

K

`

5

O

k



1100

,



:

l



1101

)

Q

M



$



1110



W



Y

n

X

1111

.





T

o



1001

1010

1011

1101

1110

1111

 

P)F789: module  # cheap PFB2=C based $odule is available for about ;1 on e+ay that provides an I $apper for this device Instead of driving each of the :E pins directly, they can be $apped onto a PFB2=C API e4tender

Page 21<

ince the $odule is based on a PFB2=C# and the PFB2=C# has B e4tended APIs, the $apping between these and the HECC=B0 are as followsPC/*04 GPIO

HD440/- 7unction

P0

'+

P1

'7

P2

6nableF+trobe

P/

B8

P

5

P$

5$

P)

5)

P,

5,

Here is a wiring sche$atic illustrating connection between HIP and the :E1@0 with I-

(o access the $odule fro$ ode6s, an np$ package called * lcd-pcfG!64* is available !hen connected to the HIP I bus nu$ber , it shows up address 0x36 ee also•

PFB2=C I driver $odule for 1@0 :E displays

•

np$ L lcdpcfB2=C

Page 219

2sing !a"a#cript and !ohnny3)i"e

ee also•

?ohnny)Five

•

?ohnny)Five L :E

$P% (he world is a sphere 8hopefully that isn't news to you9 !e can specify a point on the arth through a coordinate syste$ known as latitude 8lat9 and longitude 8lng9 Aiven a lat.lng coordinate, we know where we are (he Alobal Positioning yste$ 8AP9 is a technology that allows a AP receiver to deter$ine its own lat.lng coordinates Aiven a pair of coordinates, for e4a$ple one coordinate that says where a device is and a second coordinate saying 8for e4a$ple9 where we want to eventually be, we can calculate so$e interesting data such as how far away are we fro$ the target and what co$pass bearing we need to head to get there (here are $any applications of AP and it has entered the popular do$ain Most cell phones now have in)built AP receivers such that they can display a $ap showing your current location o$bine that with a database of driving directions and we have real)ti$e route planners where we $ount either a dedicated AP receiver or a cell phone on our car dashboards and provide destination details and the devices tell us the turns to $ake (he Alobal Positioning yste$ 8AP9 is a set of satellites in orbit (hey are continually trans$itting a very precise ti$e signal If we have a suitable receiver, we can receive the ti$e signals fro$ so$e nu$ber of those satellites that are over head at any given ti$e ince the speed of radio trans$ission is constant and not instantaneous and each satellite is producing an e4tre$ely accurate and synchroni%ed ti$e signal, then a signal clock pulse e$itted by all satellites at e4actly the sa$e ti$e will be received at very slightly staggered ti$es by the receiver as a function of the distance that the signal had to travel through space (his is the sa$e as the distance that the satellite was fro$ the receiver +y receiving enough signals fro$ a sufficient nu$ber of distinct satellites and by using co$ple4 $athe$atics, the receiver can then triangulate its own position and thus know where it is on the surface of the arth Putting that in perspective, an electronic $odule can deter$ine physically where it is uch $odules are now co$$on within your cell phone and within $any car dashboards (hey are often used in con6unction with $apping software to provide a real)ti$e $ap showing your location (he accuracy of AP is co$$only about C $eters Eevices can be picked up for about the ;1 $ark (he unit I worked with is called the AN) AP@MD which is based on the u)blo4 )@$ (he pins on this breakout board are vcc, gnd, "J and (J (his is 2D device #s such, you must use a level shifter or voltage divider between the (J pin of the AP and the "J pin of HIP as the HIP can't accept a 2D signal input ince it is a 7#"( device, we can test this on a regular P If we connect a serial port Page 220

ter$inal, we can watch the data be received (he data that co$es across is in M# for$at 8ational Marine lectronics #ssociation9 (here are various M# reader applications freely available which can for$at the data (o test the data, you should really be out)doors or otherwise have an un)obstructed view of the sky (esting in the interior of a building is basically fruitless as the AP signals will not penetrate and you will have learned nothing

(he device has an :E on the circuit that illu$inates 8flashes9 when a lock has been $ade n a HIP, we can connect the device directly to the 7#"( onnect the devices (J pin to the HIP "J through a level shifter or voltage divider, the device's "J pin to the HIP (J and the device 2D to the HIP 2D line and the devices AE to AE on the HIP

(o see it in operation, stop any gett, progra$ listening on de/tt,)0 and run a ter$inal e$ulator such as Pu**L to connect to the serial port Nou will i$$ediately start to see the Page 221

protocol data being sent by the AP device-

ee also•

7#"( 8erial9 Interface

•

Nou tube- (utorial 12 for #rduino- AP (racking

•

!ikipedia- Alobal Positioning yste$

•

!ikipedia- Aeographic oordinate yste$

&he gpsd package !ith a AP device connected to your Pi, it is now ti$e to see what it is saying (here is an e4cellent set of packages for working with AP (he packages you want to install are *gpsd* and *gpsd-clie&ts*

nce installed, we can run the $ost basic of the tools called gpsmo&$ sudo gpsmo& de/serial0

(he result of this is a curses based te4t application that shows a wealth of data related to the AP infor$ation being decoded fro$ the device-

Page 222

ore a$ongst this data are-

•

*ime L (he ti$e value received fro$ the satellites

•

Aat L (he latitude of the device

•

Ao& L (he longitude of the device

(he core though of the gpsd package is the gpsd de$on (his de$on progra$ runs on a $achine which knows how to interact with a AP device, reads and parses the data and then $akes it available as a higher level protocol !hen we run the gpsd de$on, we can then connect to the device using gpsmo& over the network 7sing the gpspipe co$$and the protocol fro$ gpsd is captured and written to stdout  #n alternative to gpsmo& is cgps which displays character data as follows-

Page 22/

ne final tool of interest to us is xgps which re/uires an J)!indows server and shows $ore details on the satellites-

Page 22

Fro$ a progra$$ing perspective, there are libraries available for both  and KK 8as well as other languages9 (hese libraries si$plify the work we need to perfor$ to get the infor$ation we desire (he single $ost i$portant data type available with this library is called gps7data7t (his contains the state and data retrieved fro$ the AP device o$e of its fields are-

Page 22$

ield

Description

gps7mask7t set timestamp7t o&li&e gps7fix7t fix i&t satelites7used i&t satelites7/isible i&t status

 #$ong these, the gps7fix7t fix $e$ber contains the data we $ost co$$only wantield

Description

timestamp7t time

Tie sta! o this i record

i&t mode

:ode o the iK • 0 – not acuired • 1 – 25 acuired • 2 – /5 acuired

double latitude

-i latitude alue

double lo&gitude

-i longitude alue

double altitude

%ltitude aboe sea leel

double track double speed

+!eed

double climb double epc double epd double eps double ept double ep, double ep/ double epx double ep,

Here is an e4a$ple of a  application which allows us to retrieve AP dataFi&clude stdio5J Fi&clude gps5J i&t mai&.i&t argc car Rarg/ST  pri&tf.")tarti&g gps clie&t test^&"Y struct gps7data7t gps7dataY i&t ret 9 gps7ope&."localost" "2#46" gps7dataY pri&tf."ret from gps7ope&9d^&" retY if .ret K9 0  retur& 0Y  gps7stream.gps7data '+*:;7E>+BAE | '+*:;7)D> >8AAY %ile.1  if .gps7%aiti&g.gps7data !00 K9 0  Page 22)

if .gps7read.gps7data K9 -1  pri&tf."fix f f^&" ^ gps7data5fix5latitude gps7data5fix5lo&gitudeY  else  pri&tf."Error^&"Y 

     

    gps7close.gps7dataY 

ee also•

gpsd

•

$ain839 L libgps

•

(he architecture of pen ource #pplications L gpsd

GP from your cell phone Nou are probably aware that your cell phone also has a AP receiver built into it (his allows your phone to know where it is and do interesting things such as show your location on a $ap 8see Aoogle Maps for e4a$ple9 an we use your phone's AP in con6unction with a Pi

(he answer is 8of course9 yes !e have a nu$ber of choices as to how we retrieve AP data fro$ the phone (he first we will look at is using the browser #ll $odern browsers are co$pliant with the H(M:2 standard and that supports access to sensor infor$ation such as AP If we load a web page, that page can contain ?avacript which re/uests the current AP location fro$ the browser (his is considered a privileged operation !e don't necessarily want any web app we visit to know our position #s such, the browser opens a pop)up dialog and re/uires us to e4plicitly confir$ that this is an allowed operation If we approve, then the data is $ade available to the page & and hence to the e$bedded ?avacript & and hence onwards to where ever that script $ay desire to send it For our purposes, this could be our "aspberry Pi Putting this all together, we now have the ability to capture our location and get it to the Pi without needing a specific AP receiver Here is an e4a$ple H(M: page which, when run on a browser on the phone and served up fro$ the Pi, will send the coordinates of the phone back to the Pi K?D:*LPE tmlJ tmlJ eadJ meta carset9"8*-G"J script src9"ttpsaIax5googleapis5comaIaxlibsIUuer,25154IUuer,5mi&5Is"JscriptJ scriptJ &a/igator5geolocatio&5get:urre&tPositio&.fu&ctio&.positio&    IMuer,5aIax. url "ttp1#251HG515101G0G0gps"  =P +ddress of P= (E)* )er/er data  lat positio&5coords5latitude l&g positio&5coords5lo&gitude Page 22,

 Y  fu&ctio&.error  co&sole5log."Error D" errorY Y co&sole5log."'aiti&g for positio&K^&"Y scriptJ eadJ bod,J ;ello %orldKK bod,J tmlJ

It works by using the H(M: geolocatio& ob6ect which has a series of functions to allow one to obtain AP sensor infor$ation fro$ within the web page !hen a sensor reading has been obtained, the values of the latitude and longitude are sent back to the Pi via a "( re/uest (he ?avacript uses the services of 6Uuery to $ake the "( re/uest ee also•

ME L 7sing geolocation

•

Making "( re/uests using 6Uuery

Video > .ebcams How can we possibly resist attaching a video input source to our HIP Many webca$s are available very cheaply and are 7+ attachable nce attached to your HIP, you should check that it has been recogni%ed # /uick way to do this is to run lsusb before plugging in the ca$era and then re)running it after the ca$era has been attached (he newly added device will be your ca$era For e4a$ple, on $y syste$Bus Bus Bus Bus

002 001 001 003

?e/ice ?e/ice ?e/ice ?e/ice

001 002 001 001

=? =? =? =?

1dHb0001 1e4e0110 1dHb0002 1dHb0002

Ai&ux ou&datio& 151 root ub :ubeter&et Ai&ux ou&datio& 250 root ub Ai&ux ou&datio& 250 root ub

nce you have located your 7+ device entry, you can ask for details that the device has $ade known to :inu4 by running the co$$andlsusb -/ -s de/ice &umberJ

(his returns a lot of detailed infor$ation and we won't be going into the details of it However, one can 6ust about see the list of different resolutions and other attributes supported by the ca$era ince we are running on HIP  and HIP  is a version of :inu4, we can leverage all the work that has been on video processing for :inu4 (his is known as the *videoClinu4* interface and $anifests itself as devices of the for de//ideo0 #n interesting thing to note is that video is considered a securable resource !hat we $ean by that is that access to your video ca$era is restricted to only certain users (his $akes sense as if your HIP were to be so$ehow co$pro$ised or you gave others access to your HIP then, in principle, they could switch on your ca$era and watch you If you were to watch $e, it would be deathly Page 22<

boring but you can obviously see that it could be abused !hen a video ca$era is attached, the device has restrictive file per$issions$ ls -l de//ideo0 cr%-r%---- 1 root /ideo G1 0 a&

# 1H36 de//ideo0

(he $ost powerful tool available for working with !ebca$s is called fs%ebcam (he fs%ebcam package is not part of the standard HIP distribution and needs to be installed using$ sudo apt-get i&stall fs%ebcam

I suggest reading the $anual page once installed before using it as it has a ton of options However, the $ost basic is$ fs%ebcam file>ameJ

for e4a$ple$ fs%ebcam image15Ipg

(his will grab an i$age fro$ the default webca$ and write into the file If this works, you should find a file on your file syste$ (o view it, I reco$$end installing the powerful package called *imagemagick* (his can be installed with$ sudo apt-get i&stall imagemagick

(here are a lot of tools associated with the package so read the $anual pages as needed ne of the useful tools is called * displa,* which displays an i$age in an J)!indows environ$ent For e4a$ple$ displa, image15Ipg

,ote- !hen I tried this, I found that $y i$age was pure black and it took $e a long ti$e to

figure out the proble$ (he !ebca$ I was using has auto)brightness enabled (he way this works is to start sa$pling fra$es when the ca$era starts up and e4a$ining the light levels fro$ those #fter a few fra$es have been received, the on)board electronics deter$ines the correct brightness level However, i$$ediately after start)up 8ie each ti$e I re/uest an i$age9, the ca$era hadn't yet seen enough fra$es to deter$ine the level and hence the black i$age (he fs%ebcam tool has an option called * --skip frame cou&tJ* which ignores the first nu$ber of fra$es before taking the desired snap For e4a$ple, I have to run$ fs%ebcam --skip 10 image15Ipg

to correctly grab an i$age

nce you have validated that the you can grab an i$age, it is ti$e to $ove on to so$e of the other options of fs%ebcam pecifying the --resolutio& %idt7x7eigtJ allows us to declare what resolution we wish to capture ince not all devices support arbitrary resolutions, deter$ine the allowable si%es For e4a$ple, by closely e4a$ining the output of lsusb -/ -s de/iceJ I found that $y ca$era supports-

Page 229

•

@C04CB0

•

324BB

•

304C0

•

1=@41CC

•

1@0410

o$e of these pairings see$ *odd* to $y eyes but I'$ sure there are good reasons why they e4ist (he i$age generated by fs%ebcam has a banner by default (his is a te4t bar at the botto$ which includes the date.ti$e the picture was captured (here are a variety of output options we can supply to control the appearance and these can be read about in $ore detail in the $an page (he one that I do want to cover though is --&o-ba&&er which disables the banner  #nother tool for our consideration is called motio& (his is /uite a catch)all tool for working with video being captured fro$ the device Its pri$ary ability is to continually watch the video input source and when the i$age contained in the video changes, perfor$ an action such as capture the changed scene In effect, this provides a $otion capture capability ne can i$agine running this application against a webca$ near a doorway and only folks arriving or leaving are recorded and not the e$pty spaces in between #lternatively, one could record so$e wildlife prone area and only when an ani$al enters the scene, will the recording start In addition to detecting $otion in a scene, the tool allows us to strea$ video over a network (he fra$e rate is poor & $aybe only a few fra$es.second 8if that9 but it does work and is si$ple to use (he tool is configured by a rich and detailed configuration file called motio&5co&f (he search order is to look for motio&5co&f in the current directory and then in a directory called 5motio& in the ho$e directory and then at etcmotio&motio&5co&f It is likely that this file will have to be edited before you use motio& (he tool can be started as a de$on which puts itself into the background However it can also be forced to run in the foreground when testing (o run in the foreground, use$ sudo motio& -&

 #gain, this is not supplied with a default HIP distribution so we $ust install it with$ sudo apt-get i&stall motio&

Motion can be started as either a de$on or in non de$on $ode !hen setting it up, I reco$$end running in the non)de$on $ode (his can be controlled by passing in the *-&* flag (o say that there are a lot of options associated with $otion is an understate$ent !e will see so$e of these in the following sections ee also• Page 2/0

7sing a standard 7+ webca$

•

$an819 L fswebca$

•

I$ageMagick L ho$e page

•

Motion L ho$e page

•

$an819 L $otion

•

cheese

•

avconv docu$entation

treaming a we!cam video  #l$ost without e4ception we will want so$e techni/ue for strea$ing webca$ video (his $eans taking the source of the video and sending it live over the network to be shown elsewhere (he motio& package has this capability baked into it (he first para$eter we will look at is called stream7port (his is the (P.IP port nu$ber that $otion will listen upon for inco$ing client re/uests # client is a browser that wishes to view the video strea$ # value of 0 switches it off

(he ne4t setting is called stream7maxrate which is the nu$ber of fra$es.second that should be atte$pted to be delivered (he default here is  & which will not give a steady strea$ but will be very 6erky (his para$eter co$bines with framerate which is the $a4i$u$ capture rate fro$ the ca$era It is also set very low (he strea$ rate that you actually see will be no better than the s$aller of these two para$eters ince the video strea$ consu$es bandwidth, there is usually no purpose in strea$ing i$ages if nothing is changing ince $otion is configured to be able to detect changes, another para$eter called stream7motio& co$es into play (he values of this para$eter can be o& or off !hen o&, the video is ( strea$ed at $ore than 1 fra$e.second when there is no detected $otion in the scene However when $otion is detected, video strea$ starts Here are so$e suggested settings for $a4i$u$ fra$e ratesstream7port G0G1 stream7maxrate 100 stream7motio& off framerate 100

 #nother possibility for video strea$ing is c/lc

ecording a we!cam image for a period of time  # not unco$$on re/uest is to record a webca$ i$age for a period of ti$e For e4a$ple, we $ay have a sensor that acts as a trigger & for e4a$ple a pro4i$ity detector ur pu%%le then beco$es that once we detect a signal, how can we record a video for so$e duration (he $otion tool is all about sensing $otion and, as such, it doesn't nor$ally trigger recording until it does sense that $otion However, we can instruct the tool that even if it doesn't detect $otion, it should behave as though $otion is present !e can use the emulate7motio& setting to achieve this etting it to on causes $otion to believe that there is always $otion Page 2/1

and it will start recording If we set it off, then it will no longer be e$ulating $otion but real $otion will trigger the recording If we only wish to record when we want to record, then we can disable detection of $otion & this says *Eon't watch the video output and look for $otion* & however, if we switch on emulate7motio& while detection is disabled, then video will be recorded Is this a hack Possibly, but it works !e can use "( re/uests to control this endingttp1#251HG515101G0G00detectio&pause

pauses detection whilettp1#251HG515101G0G00co&figset`emulate7motio&9o&

e$ulates $otion andttp1#251HG515101G0G00co&figset`emulate7motio&9off

disables e$ulation ince "( re/uests can be sent either based on the " scheduling de$on or by application logic when a sensor is triggered, we now have the ability to capture video under application control

ecording a video !e can record a video using ffmpeg For e4a$ple$ ffmpeg -f /4l2 -framerate 2! -/ideo7siCe H40x4G0 -i de//ideo0 output5mk/

!e can add the -t seco&dsJ option to force recording for so$e period of ti$e in seconds ee also•

ff$peg docu$entation

•

avconv

Playing video (he */lc* package provides video over J)!indows $ sudo apt-get i&stall /lc

+e aware that this is a big package !hen launched it provides the ability to view video (he video files can be opened as desired

Page 2/2

ther players for playing video include $player.$player

"arcode and / )ode scanning +arcodes and U" codes can be generated and scanned #n e4cellent application called Cbarcam is available for 6ust that purpose

ee also•

G+ar ho$e page

Open)$ – e!cam programming If we consider an i$age as a rectangular array of pi4els, we need a data structure to represent the i$age In penD, the data type is the Mat 8for Matri49

(he source of a video co$es fro$ the Dideoapture class !e create an instance of this class usingideo:apture capY

and then open it to a video source 8!ebca$9cap5ope&.0Y

(o obtain an i$age for the capture device, we can now usecap5read.imageY

 #t this point, we have an i$age in the Mat ob6ect

Page 2//

nce we have a Mat that contains data, we can interrogate it to $anipulate pi4els !e can retrieve a pi4el value with the at.ro% col and can also set the value the sa$e way  # co$$on value of a pi4el is 3 bytes, one each for red, green and blue (his can be represented in penD as a ec3b 8a vector of 3 bytes9 (he order of pi4els is +A" and not "A+ !e can read a static i$age fro$ the file syste$ using the * imread* $ethod If we wish to create a window to show graphics, we can create a na$ed window using *&amed'i&do%* (o display an i$age in a window use *imso%* ee also•

penD L Installation in :inu4

•

penD #PI "eference docs

nalog to -igital con'ersion – -C=
Page 2/

 # conversion is re/uested when  8pin 19 goes fro$ high to low It should stay low until the reading of the analog signal and its conversion is co$plete  # clock signal starts low, goes high and then back to low (he clock signal should be sent to the :5 8pin =9 (he data in 8EI9 is used to provide instructions to the I Its value is clocked in on the rising edge of the clock signal Following the start of the conversion, the EI is used to send in three bits

•

First L a tart +it used as a flag (his should be a 1 value

•

econd L a A:.EIF selection bit L (he I can work in an absolute or relative $ode in ter$s of analy%ing the inco$ing analog voltage value (he A: 8on9 8ingle nded9 $ode $eans that the absolute value on the channel will be used while the EIF 8off9 8Eifferential9 $ode will co$pare the difference between the values on H0 8pin 9 and H1 8pin 39

•

(hird L an EE.IA selection bit If we are in A: $ode, the value of this selection chooses between reading fro$ channel 0 8H09 or channel 1 8H19 If we are in EIF $ode, this selection choose which of the channels should be subtracted fro$ the other  8we cant have negative values9

Following this we get B bits of analog converted data twice (he first B bits are M+ first while the second B bits are :+ first (he signal data can be found on E0 8pin 29 (he following is reproduce fro$ the data sheet and pictorially illustrates the ti$ing diagra$s-

Page 2/$

(he high level bit banging algorith$ is as followsset :AN mode 9 Dutput set :) mode 9 Dutput  (estart ere for future reads set ?=D mode 9 Dutput set :AN 9 0 set :) 9 0 set ?=D 9 1  )tart bit dela, set :AN 9 1 dela, set :AN 9 0 dela, set ?=D 9 1  )
9 0  :oose ca&&el 0 9 1 mode 9 =&put 9 0

set :AN 9 1 dela, set :AN 9 0 dela, loop for G set :AN 9 1 get ?=D 
set :) 9 1

 #lternatives to the #E0B3 $ay be the MP300, #E1013.101C.1012

Here is a ?avacript progra$ that i$ple$ents this algorith$ using the ?avacript * o&off* package RR  R adc0G32 module  R "use strict"Y /ar
clkPi& 9
dioPi&5%rite),&c.;=<;Y  )tart bit sleep5usleep.?EA+LY clkPi&5%rite),&c.;=<;Y sleep5usleep.?EA+LY clkPi&5%rite),&c.AD'Y sleep5usleep.?EA+LY

       

dioPi&5%rite),&c.;=<;Y )
         

dioPi&5%rite),&c.AD'Y  :oose ca&&el 0 clkPi&5%rite),&c.;=<;Y sleep5usleep.?EA+LY dioPi&5set?irectio&."i&"Y clkPi&5%rite),&c.AD'Y sleep5usleep.?EA+LY

clkPi&5%rite),&c.;=<;Y   sleep5usleep.?EA+LY   clkPi&5%rite),&c.AD'Y   sleep5usleep.?EA+LY

 )kip a clock

/ar /alue 9 0Y for ./ar i90Y iGY i]]    clkPi&5%rite),&c.;=<;Y /ar bit 9 dioPi&5read),&c.Y /alue 9 ./alue  1 | bitY sleep5usleep.?EA+LY   clkPi&5%rite),&c.AD'Y sleep5usleep.?EA+LY  csPi&5%rite),&c.;=<;Y retur& /alueY Y  E&d of getalue.

nalog to -igital con'ersion – -%@=@A (his is a pricier I at about ;10 on e+ay It provides a 1 bit resolution for #.E conversion and is controlled by an I bus It supports either 33D or 2D supplies It can support either C single)ended channels or  differential channels

Page 2/<

(he device is e4tre$ely power efficient and can operate in a nu$ber of power $odes In single)shot $ode, it sa$ples the value and $akes it available and then goes into a lower power $ode In continuous operation $ode, it starts calculating the ne4t sa$ple as soon as the previous has been calculated (he pin out on the device isPin

1abel

Description

1

#55

/./#4 $#

2

*=5

*round

/

+C8

I2C Clock  



+5%

I2C 5ata

$

%55'

%ddress selection

)

%8'T

5igital co!arator F Conersion ready

,

%0

Channel 0

<

%1

Channel 1

9

%2

Channel 2

10

%/

Channel /

(he device has four registers at the following addressesddress

Re&ister

0

Conersion register   Q1$KR – 5ata 511K50 – 12 bits o data Q/K0R – 0 – not used

1

Conig registerK

Page 2/9

Bit

'egister

5escri!tion

1$

3+

3!erational statusK 7 – 1 – Begin a conersion ' – 0 – Currently conerting ' – 1 – =ot currently conerting

1K12

:UE

In!ut ulti!leer. 5eault 000 2its

Positie

Ne&atie

000

%I=0

%I=1

001

%I=0

%I=/

010

%I=1

%I=/

011

%I=2

%I=/

100

%I=0

*=5

101

%I=1

*=5

110

%I=2

*=5

111

%I=/

*=5

11K9

P*%

Prograable gain a!liier. 5eault 010

<

:356

:odeK 0 – Continuous 1 – Po"erdo"n single shot ?deault@

,K$

5'

5ata rate. 5eault 100 ?1)00s!s@



C3:P>:356

Co!arator ode. 5eault 0

/

C3:P>P38

Co!aritor !olarity. 5eault 0

2

C3:P>8%T

8atching co!aritor. 5eault 0.

1K0

C3:P>U6

Co!aritor ueue. 5eault 11

2

8o>threshold register  

/

Hi>threshold register  

!hen we send a write co$$and we send 3 bits co$posed of%ddress

'egister

5ata high

5ata lo"

(he default address of the device is 04CB L 0b100 1000 (his can be altered by wiring the +??( pin to different values !hat this allows us to do is to have $ultiple instances of the devices attached to our I bus If we needed $ore than C analog inputs, this would be essential ddr Pin

I+C ddress

*=5

100 1000 ?0<@

#55

100 1001 ?09@

+5%

100 1010 ?0a@

+C8

100 1011 ?0b@

Here is a typical sche$atic diagra$-

Page 20

!hen plugged into chip, we can see that it is available by running$ sudo 0 00 10 -20 -30 -40 -!0 -H0 -60 --

i2cdetect -, 2 1 2 3 4 ! -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --

H ---------

6 ---------

G # -- --- --- -88 -48 --- --- --

a --------

b --------

c --------

d --------

e --------

f --------

and seeing it present at address 0x4G ee also•

 #E1012 ho$e page

•

Eatasheet

2sing !a"a#cript

 #n e4isting library for ?avacript is available ee np$ node)ads1412 8alphacharlie.node) ads1412 on Aithub9 (his has the following $ethods e4posed-

•

read#Einglended8channel, gain, sa$plesPerec, callback9

◦ channel L the channel to read fro$  values 0)3 ◦ gain L default us @1CC Page 21

◦ sa$plesPerec L default is 20 ◦ callback8error, data9 •

read#EEifferential8chP,, ch, gain, sa$plesPerec, callback9 read#EEifferential8chP

•

read#EEifferential018gain, sa$plesPerec, callback9 L Aet the differential between channels 0 and 1

•

read#EEifferential038gain, sa$plesPerec, callback9 L Aet the differential between channels 0 and 3

•

read#EEifferential138gain, sa$plesPerec, callback9 L Aet the differential between channels 1 and 3

•

read#EEifferential38gain, sa$plesPerec, callback9 L Aet the differential between channels  and 3

•

startontinuousonversion8channel, gain, sa$plesPerec, callback9

•

stopontinuousonversion8callback9

•

get:astonversion"esults8callback9

•

startinglendedo$parator8channel, thresholdHigh, thresh old:ow, old:ow, gain, sa$plesPerec, active:ow, traditionalMode, latching, nu$"eadings, callback9

•

startEifferentialo$parator8chP, ch, thresholdHigh, threshold:ow, gain, startEifferentialo$parator8chP, sa$plesPerec, active:ow, traditionalMode, latching, nu$"eadings, callback9

!hile e4peri$enting with this code, it was found that the I bus was hard coded to *de/i2c-1* which is no good for a HIP of kernel CC where our bus is * de/i2c-2*  #n issue has been raised on the AitHub pro6ect #s a circu$vention, the underlying code can be edited to change the bus ee also•

np$- node)ads1412

•

Aithub- alphacharlie.node)ads1412

ccelerometer and $yroscope – *PU6=A= /aka $6A9@0 (he MP7)@020 is a 33D device  #n accelero$eter $easures the force of linear acceleration i$ply put, that when an ob6ect is at rest 8ie sitting peacefully on your desk9, it is not being accelerated 8well & it actually is but we'll co$e back to that later9 !hen you start to to $ove the ob6ect, it undergoes acceleration ote that this is not the sa$e as speed #cceleration is the rate of change in speed over ti$e !hen you are sitting as a passenger in your car and the car is $oving at a constant speed and if the ride were very s$ooth and you closed your eyes, you wouldn't know you were $oving However, if the gas or brake are pressed, your car would change speed and you would feel acceleration while the speed changed Nou would feel yourself Page 22

pushed back in your seat when the gas is pressed and you would feel yourself wanting to $ove forward if the brake is pressed i$ilarly, i$ilarly, if you stand in an elevator and press a button, you feel yourself being pushed into the floor when it starts to rise and you would find yourself wanting to rise when it co$es to a stop stop #cceleration is a vector /uantity $eaning that it has a directional /uality associated with it In your car 8assu$ing you you are driving forward and we call the forward direction x9 then stepping on the gas produces an acceleration in the x direction while stepping on the brake produces an acceleration in the -x direction i$ilarly with the elevator, when you rise there will be an acceleration in the C direction and when you stop, there will be an acceleration in the -C direction (here is one $ore twist twist to the story story & gravity gravity #lthough you $ay not have thought about it, as you you sit in your chair there is a force acting on you that wishes to accelerate you (hat force is called gravity and the direction of the acceleration is -C If it weren't for the chair, chair, your body would be accelerated towards the floor ven though your body isn't $oving, we can consider this this an acceleration force being applied !hat this $eans for us is that when a device such as the the MP7)@020 is sitting on your desk, it will be reporting that it is accelerating downwards (he practical i$plication of this is very very interesting If the MP7)@020 is flat on the the desk, it will report an acceleration in its -C direction If we now were were to tilt the device, the acceleration due to gravity is still present but now the direction of that force will have changed (he $agnitude of the acceleration will re$ain the sa$e but the $easure$ents will now show it spread over the x, , and C a4ises !orking backwards, by e4a$ining the the values of the acceleration on the x, , and C a4ises, we can calculate the orientation of the device relative to the direction of gravity 8ie relative to up and down9 Having 6ust discussed the concept of $easure$ent of acceleration through the notion of an accelero$eter, we we can now look at how a gyroscope co$es into play play # gyroscope gyroscope $easures the change in velocity 8if at all9 of a device rotating around its own a4is, # gyroscope gyroscope $easures changes in angular velocity (he MP7)@020 co$bines these to $easure both linear acceleration and angular velocity (he device $easures both /ualities in the x, , and C a4is and hence is considered a $easure$ent in @ degrees of freedo$ 8linear acceleration in x, , and C and angular velocity in x, , and C9 (he $easure$ent values values have a 1@ bit resolution resolution If our goal is to $easure the orientation of the device, we $ay be able to see that the orientation can be found by e4a$ining the accelero$eter values however these values only result in accurate answers if the device is at rest If it is $oved, then the the acceleration due to $ove$ent can produce 6ittery results results If we look at the gyroscope, if we start fro$ a known orientation 8eg flat on the desk9, then in principle we should also be able to deter$ine the device's current orientation by adding together all the gyroscopic changes that have happened to it since its original known 8calibrated9 position 7nfortunately, 7nfortunately, both of these techni/ues introduce errors 7sing the accelero$eter, accelero$eter, we can deter$ine deter$ine our orientation by averaging values over ti$e to re$ove 6itter 6itter #s such, it gives good values over ti$e but poor for short ter$ $easure$ent (he gyroscope gives us good angular $o$entu$ values in the the short ter$ but the errors accu$ulate over ti$e when we try and calculate the orientation of the device fro$ its base state by successive addition of delta delta values Fortunately, Fortunately, we can Page 2/

co$bine these two techni/ues through a variety of algorith$s to give us a good value that is built fro$ the co$bination of the two $easure$ents (he MP7)@020 device connects via an I bus 8default address is 0xHG but can be changed to 0xH#9 (his is 33D device and hence is safe to connect to to HIP pins directly directly

(he device has the following pins e4posed fro$ the breakout boardsPin

Desc Descrriptio ption n

::

/./#

<>?

*round

):A

I2C Clock 

)?+

I2C 5ata

@?+

%uiliary I2C 5ata

@:A

%uiliary I2C Clock 

+?D

I2C address selection4 either

0xHG or 0xH#. 8o" N 0xHG4 high N 0xH#.

=>*  # sa$ple wiring of the device to HIP looks as follows-

Page 2

 #fter wiring, if we run icdetect we we will see the device$ sudo 0 00 10 -20 -30 -40 -!0 -H0 -60 --

Page 2$

i2cdetect -, 2 1 2 3 4 ! -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --

H ---------

6 ---------

G # -- --- --- -88 --- --- -68 --

a --------

b --------

c --------

d --------

e --------

f --------

Re&ister

O77set

Name

Description

0x3B

0

%CC68>E3UT>H

%ccelE High

0x3:

1

%CC68>E3UT>8

%ccelE 8o"

0x3?

2

%CC68>G3UT>H

%ccelG High

0x3E

/

%CC68>G3UT>8

%ccelG 8o"

0x3



%CC68>(3UT>H

%ccel( High

0x40

$

%CC68>(3UT>8

%ccel( 8o"

0x41

)

T6:P>3UT>H

Te! Hi gh

0x42

,

T6:P>3UT>8

Te! 8o"

0x43

<

*G'3>E3UT>H

*yroE High

0x44

9

*G'3>E3UT>8

*yroE 8o"

0x4!

10

*G'3>G3UT>H

*yroG High

0x4H

11

*G'3>G3UT>8

*yroG 8o"

0x46

12

*G'3>(3UT>H

*yro( High

0x4G

1/

*G'3>(3UT>8

*yro( 8o"

Nou will so$eti$es see these devices referred to as Inertial Measure$ent 7nits 8IM7s9 8 IM7s9 (he value returned fro$ the the accelero$eter is a raw value (he actual result we we want is ) $easured in gravities 8g9 which is about <B1 $s  (he device has various sensitivities built built in (o get to the real value, we need to divide by a scaling factor as show belowcceleration 1imit

(ensitiity actor

2g

1) /<

g

<1 92


0 9)

1)g

20 <

(hus to get the re/uired value fro$ the raw value we would use the e/uationrequired value =

  raw value value sensitivi sensitivity ty factor factor

+y default, the device is configured for a g acceleration li$it i$ilarly, i$ilarly, there is an angular velocity scaling-

Page 2)

n&ular Velocity 1imit

(ensitiity actor

2$0Fs

1/ 1

$00Fs

)$.$

1000Fs

/2.<

2000Fs

1).

(echnical task & send in accel values J, N and G (he np$ package called * mpuH0!0* was tested on HIP and found to work after so$e s$all tweaks (hese tweaks were changed in a pull)re/uest that has been sub$itted ?ohnny)Five provides a $odule for accelero$eters accelero$eters which includes the MP7)@020 MP7)@020 #t a high level, we use this as follows/ar accel 9 &e% fi/e5+ccelerometer. co&troller "P8H0!0" bus 2 Y accel5o&."ca&ge" fu&ctio&.   a&dle data ca&ges 555  tis dotJ pitc roll i&cli&atio& x , C acceleratio& Y

?ohnny)Five also provides a $odule for for gyroscopes which includes the MP7)@020 #t a high level, we use this is as follows/ar g,ro 9 &e% fi/e5<,ro. co&troller "P8H0!0" bus 2 Y Page 2,

g,ro5o&."ca&ge" fu&ctio&.   a&dle data ca&ges 555  tis dotJ x , C pitc roll ,a% rate is:alibrated Y

(he class e4poses two events (he first is called *change* which is fired when ever a detection of change $ore than the configured threshold (he second is called *data* which will be fired as often as possible Here is an e4a$ple ?ohnny)Five application"use strict"Y /ar fi/e 9 reUuire.WIo&&,-fi/eWY /ar cipio 9 reUuire.Wcip-ioWY /ar board 9 &e% fi/e5Board. io &e% cipio. Y board5o&.Wread,W fu&ctio&.  /ar g,ro 9 &e% fi/e5<,ro. co&troller "P8H0!0" bus 2 Y g,ro5o&."ca&ge" fu&ctio&.    debuggerY co&sole5log."<,ro ca&gedK pitc9" tis5pitc " roll9" tis5roll " ,a%9" tis5,a%Y Y co&sole5log."g,ro i&itialiCedKK"Y Y

ee also•

 #ccelero$eters

•

(ilt ensing 7sing a (hree)#4is #ccelero$eter 

•

MP7)@020 Eata heet

•

MP7@020 "egister Map and Eescriptions

•

MP7 )@020 #ccelero$eter K Ayro

•

I devlib L MP7 )@020

•

Filters

•

Invenense L MP7)@020 Ho$e Page

•

Ayroscopes and #ccelero$eters on a hip

•

7sing an accelero$eter for inclination sensing

•

Nou(ube- MP7)@020 Eata with a o$ple$entary Filter 

•

?ohhny)Five- Ayro

Page 2<

&he math of (ccelerometers ur real world is co$posed of three spatial di$ensions In nglish we $ight think of these as left.right, up.down and in.out 8or forward.back9 In our $ath, we will label these by the co$$on 4, y and % If we want to think about the orientation of so$ething, we can think of it as the rotation about these a4is !e define the rotation around the 4 a4is as *roll* designated by the sy$bol * SL. 7e deine the rotation around the y ais as L!itchL designated by the sybol LL and inally4 "e deine the rotation around the ; ais as Lya"L designated by the sybol LL. +o4 to think about the orientation o an obDect4 "e can think about its roll4 !itch and ya". %is

Name

(ymbol



roll

S

y

!itch



;

ya"



 =o"4 let us erge in the notion o ho" "e are going to easure our roll4 !itch and ya". %ssuing no acceleration o our deice ?I.e it is stationary@ then there "ill be a constant orce on it o 1g in the ; ais. +o the orce easured in the ; ais "ill be 1 and  and y "ill both be 0. %s "e tilt the deice ro its hori;ontal orientation4 that orce "ill start to be distributed across ulti!le ais and not Dust the ; ais. +o a tilt "ill !roduce a ne" easured orce alue in both  and y. %nd here coes the agic. The easured orce change is !ro!ortional to the roll and !itch angles. But "ait4 "hat about the ya"V 7ell M i "e think about it4 a rotation around the ; ais does not change the tilt o "hat "e "ant to easure. Think o it like this4 i "e hae a !erectly lat table to! and !lace soe arbles on its surace4 i "e tilt the table let or right4 the arbles "ill roll. I "e tilt it or"ard or back4 the arbles "ill roll. Ho"eer4 i "e are gentle and rotate the table around its central ertical ais4 the arbles "ill not roll. They "ill reain in their sae !osition relatie to the table. %nother "ay to think about this is to hold your cell !hone in your hand lat "hile sitting on a chair. I you no" s!in around on your chair4 hae you changed the LtiltL o your cell !honeV I "ould say no. 7hat this eans to us is that "e can calculate the orientation o our deice only by iguring out the roll and !itch. The ya" becoes iaterial to our story ?or Dust no"@. By soe ath4 "e can ind thatK tan

( Φ )=

tan

( Θ )=

G py G pz

−G px

√  G py + G pz 2

2

+ee alsoK •

7sing an #ccelero$eter for Inclination ensing

•

7nderstanding uler #ngles

Page 29

$isuali%ing orientation It is all very good getting raw nu$bers representing the a$ount and direction of force on our device against different a4is, but triplets of nu$bers isn't at all intuitive to our ways of thinking Instead, what we want is a $echanis$ to *see* the orientation of the device ince orientation is inherently a three di$ensional physical consideration, what we want is to visuali%e the data as a 3E scene (here are $any 3E progra$$ing packages on the Internet with varying degrees of sophistication and capabilities ince $y belief is that all user  interfaces should be browser based as opposed to thick client, I wanted one that could run in a browser I also wanted one that is open source For this I chose *tree5Is*

ee also•

three6s

Compass – H*CA<
(he pin configuration for AN=1 is 8:eft)"ight as seen fro$ chip side with connector at top9-

Page 2$0

Pin

unction

?(?L

5ata readyFInterru!t

)?+

I2C 5ata line

):A

I2C Clock line

<>?

*round

::

Oe oltage – /./#

(he pin configuration for the ?)MC< is 8:eft)"ight as seen fro$ chip side with connector at top9-

Pin

unction

33

Oe oltage – /./#

?(?L

5ata readyFInterru!t

)?+

I2C 5ata line

):A

I2C Clock line

<>?

*round

:: ]!

Oe oltage – $#

(he $odule $akes its data available via the I bus (he I address of the device is 0x1E If we run $ i2cdetect -, 2

we will see the device as being present00 10 20 30 40 !0 H0 60

0

1

2

--------

--------

--------

3 ---------

4 ---------

! ---------

H ---------

6 ---------

G ---88 ----

# --------

a --------

b --------

c --------

d --------

e f -- -1e --- --- --- --- --- --

Fro$ I there is a set of registers that can be accessed-

Page 2$1

ddress

Description

ccess

00

Coniguration register %

'ead F 7rite

01

Coniguration register B

'ead F 7rite

02

:ode register

'ead F 7rite

0/

5ata out!ut E :+B register

'ead

0

5ata out!ut E 8+B register

'ead

0$

5ata 3ut!ut ( :+B register

'ead

0)

5ata 3ut!ut ( 8+B register

'ead

0,

5ata out!ut G :+B register

'ead

0<

5ata out!ut G 8+B register

'ead

09

+tatus register

'ead

10

Identiication register %

'ead

11

Identiication register B

'ead

12

Identiication register C

'ead

(hink of the device as having a register cursor !e can $ove the cursor si$ply by sending the id of the register to $ove to For e4a$ple, sending the device 0x03 will $ove the cursor to register 3 ubse/uent reads will read fro$ the cursor location and auto)incre$ent the cursor o $oving to register 3 and reading H bytes will read the ne4t H register values O0x03-0x0G onfiguration "egister # 8register 009 is as followsName

2its

Description

,

'esered. :ust be 0.

:%

)K$

%eraged sa!les !er easureentK W 00 N 1 ?deault@ W 01 N 2 W 10 N  W 11 N <

53

K2

5ata out!ut rate in easureentsFsecondK W 000 N 0.,$ W 001 N 1.$ W 010 N / W 011 N ,.$ W 100 N 1$ ?deault@ W 101 N /0 W 110 N ,$ W 111 N 'esered

:+

1K0

:easureent coniguration W 00 – =oral ?deault@ W 01 – Positie bias W 10 – =egatie bias W 11 – 'esered

onfiguration "egister + 8register 019 is as followsPage 2$2

Name

2its

Description

*=

,K$

*ain aluesK W 000 N 1/,0 W 001 N 1090 ?deault@ W 010 N <20 W 011 N ))0 W 100 N 0 W 101 N /90 W 110 N //0 W 111 N 2/0

K0

'esered. :ust be 0.

Mode "egister 809 Name

2its

Description

;)

,

High s!eed I2C control

)K2

'esered. :ust be 0.

1K0

3!erating odeK W  N Continuous

?

W W W

00 01 N +ingle easureent ?5eault@ 10 N Idle ode 11 N Idle ode

(he three identification registers return the #II values ' ;', '4' and ':' (o create an angle in degrees, the following for$ula can be useda&gle 9 ata&2..double,.doublex R .1G0  35141!#2H! ] 1G0Y  a&gle i& degrees

(he driving logic at a high level isunction

Description

7rite 002

+elect ode register  

7rite 000

Continuous easureent ode

7rite 00/

+elect register /

'euest ) bytes

'ead the net ) bytes

'ead ) bytes

E4 (4 G alue !airs :+BF8+B

we co$bine M+ and :+ of data withdataS0T  G | dataS1TY

 #ttach$ent of the device to HIP is particularly easy #s you can see it only needs C wires to connect Page 2$/

Here is a sche$atic sc he$atic of how an instance of the board $ay be wired to HIP HIP

!hen we use a co$pass, the result we usually want is *which way is orth* n a real physical co$pass, we have a needle that points in that direction direction and we know our answer (hrough a digital device, what we should e4pect to get back is an angle that the device would have to be oriented for it to point orth (his assu$es that there is a reference $ark on the device fro$ which the angle has $eaning !hen e4peri$enting with the device, don't bring strong $agnets too close to the device as it $ay beco$e $agneti%ed or otherwise da$aged ee also•

Eata Ea ta sh shee eett

•

parkfun par kfun (utor (utorial ial

•

 #rduino ano K AN)=1 8Eigital o$ o$pa pass ss $odule $odu le 9 K : :E E

•

lec l ectr trod odra rago gon n ) HM HM 2B 2BB3 B3 : ) (h (hre ree e)# )#4i 4is s o$pa o$pass ss

•

Nou(ube L #rduino L #rduino How (o- HM2BB3: o$pass Magneto$eter (utorial (utorial

•

Nou(ube L 7se the HM2BB3: 3)a4is sensor with an #rduino L (utorial

•

Nou(ube L :et's build an #rduino electronic o$pass using the HM2BB3: and a "ing of :Es ) (utorial

•

!ikipedia L atan

•

Aithub L #rduino L #rduino :ibrary

Page 2$

.sing iring)*+P !e can easily use the !iringHIP I functions to interact with the device #ccess is relatively si$ple with with no co$ple4 operations nce we have retrieved the values, we can perfor$ the $ath to calculate the angle to $agnetic orth Fi&clude Fi&clude Fi&clude Fi&clude Fi&clude Fdefi&e Fdefi&e Fdefi&e Fdefi&e Fdefi&e Fdefi&e Fdefi&e Fdefi&e Fdefi&e Fdefi&e

stdi&t5J stdlib5J stdio5J mat5J %iri&g-:;=P5J

P= 35141!#2H! ;:!GG3A7D?E7:D>*=>8D8) .0x00 ;:!GG3A7+??(E)) .0x1e ;:!GG3A7(E<7D?E .0x02 ;:!GG3A7(E<7)B7@ .0x03 ;:!GG3A7(E<7A)B7@ .0x04 ;:!GG3A7(E<7)B7L .0x0! ;:!GG3A7(E<7A)B7L .0x0H ;:!GG3A7(E<7)B7O .0x06 ;:!GG3A7(E<7A)B7O .0x0G

/oid ceck(:.i&t rc car Rtext  if .rc  0  pri&tf."Error s - d^&" text rcY   exit.-1Y   i&t mai&.i&t argc car Rarg/ST  pri&tf.";:!GG3A starti&g^&"Y  )etup 'iri&g :;=P   %iri&g:;=P)etup.Y  Dpe& a& =2: co&&ectio& i&t fd 9 %iri&g:;=P=2:)etup.2 ;:!GG3A7+??(E))Y ceck(:.fd "%iri&gPi=2:)etup"Y pri&tf."id9^"c c c^"^&" %iri&g:;=P=2:(ead(egG.fd 10  %iri&g:;=P=2:(ead(egG.fd 11  %iri&g:;=P=2:(ead(egG.fd 12 Y  Perform =2: %ork %iri&g:;=P=2:'rite(egG.fd ;:!GG3A7(E<7D?E ;:!GG3A7D?E7:D>*=>8D8)Y %ile.1  ui&tG7t msb 9 %iri&g:;=P=2:(ead(egG.fd %iri&g:;=P=2:(ead(egG.fd ;:!GG3A7(E<7)B7@Y if .msb 99 -1    perror."msb"Y  ui&tG7t lsb 9 %iri&g:;=P=2:(ead(egG.fd %iri&g:;=P=2:(ead(egG.fd ;:!GG3A7(E<7A)B7@Y if .lsb 99 -1    perror."lsb"Y  sort x 9 msb  G | lsbY msb 9 %iri&g:;=P=2:(ead(egG.fd ;:!GG3A7(E<7)B7LY lsb 9 %iri&g:;=P=2:(ead(egG.fd ;:!GG3A7(E<7A)B7LY sort , 9 msb  G | lsbY

Page 2$$

msb 9 %iri&g:;=P=2:(ead(egG.fd ;:!GG3A7(E<7)B7OY lsb 9 %iri&g:;=P=2:(ead(egG.fd ;:!GG3A7(E<7A)B7OY sort C 9 msb  G | lsbY double a&gle 9 ata&2..double , .doublex R .1G0  P= ] 1G0Y pri&tf."x9d ,9d C9d - a&gle9f^&"x a&gle9f^&"x , C a&gleY   sleep.1Y  retur& 0Y 

ee also•

!iring)HIP

•

I

.sing 5ohnny-Fiv 5o hnny-Five e ?ohnny)Five provides a $odel for co$pass interaction that includes the HM2BB3:

!e construct a new instance of a co$pass with/ar compass 9 &e% fi/e5:ompass. co&troller ";:!GG3A" bus 2 Y

nce we have a co$pass, we can use two properties e4posed fro$ it which are * eadi&g* and *beari&g* (he heading is is the the current heading in degrees (he bearing is the co$pass beating which contains the following properties-

•

poi&t L # cardinal direction such as *north*, *south*, *east*, *west*

•

abbr L #n abbreviation of the point such as **, ** and *b*

•

low, $id, high

(wo events are fired fro$ the o$pass ob6ect (hese are *ca&ge* and *data* (he *ca&ge* event is fired when the value of the co$pass changes while * data* is fired as often as possible Here is a sa$ple that logs the current heading If we turn the co$pass $odule, we will see the changes take place in real)ti$e"use strict" /ar fi/e 9 reUuire.WIo&&,-fi/eWY /ar cipio 9 reUuire.Wcip-ioWY /ar board 9 &e% fi/e5Board. io &e% cipio. Y board5o&.Wread,W fu&ctio&.  let compass 9 &e% fi/e5:ompass. co&troller ";:!GG3A" Page 2$)

bus 2 Y compass5o&."ca&ge" fu&ctio&.  co&sole5log.":ompass /alue ca&ged " ] at5rou&d.compass5eadi& at5rou&d.compass5eadi&gY gY Y Y

ee also-

•

?ohnny)Five ?ohnn y)Five L o$pas o$pass s

&ilt compensation of the compass !hen the co$pass $odule is perfectly planar, it returns a good value but if it is tilted, then the value is no longer true true :ook at the following following diagra$ and i$agine i$agine your co$pass center in a perfect hori%ontal plane #t that ti$e, ti$e, there will be no roll and no pitch For our purposes, the yaw of the board will be pointing vertically straight straight up and we don't care (he value of the co$pass will be correct However if the board is tilted with with roll and pitch, then the co$pass value is no longer accurate However, given then value $easured fro$ the co$pass and if we have the values of roll and pitch, we can co$pensate and calculate a correct co$pass value

 #gain by looking at the above i$age, consider an accelero$eter accelero$eter (his will $easure the force of gravity and gives us a reference to the orientation of the the co$pass sensor !hen the sensor is hori%ontal, the acceleration $easured will be e4clusively down the G a4is however when the sensor is titled, the acceleration will be distributed across J, N and G and by using $ath, we can deter$ine the orientation of the the board #s a side note, when the board is hori%ontal, the co$pass bearing will be the yaw value !e will define the following definitions-

Page 2$,

S – !hi

'oll ?E@

X – theta

Pitch ?G@

 – !si

Ga" ?(@

ee also•

I$ple$enting a (ilt)o$pensated (ilt)o$pensated eo$pass e o$pass using #ccelero$eter and Magneto$eter ensors

•

!ikipedia- #4es !ikipedia- #4es conventions

.sing the shell  #lthough the raw data can be retrieved using the i2cget co$$and it is unlikely that you will be perfor$ing any calculations in shell script due to the shell's poor ability to perfor$ $ath ne $ight try using the 7ni4 co$$and bc

Temperature and pressure – B*P@<= (he +MP1B0 $odule can be found on e+ay for less than ;00 ;00 (his device provides both te$perature and baro$etric pressure readings via an an I bus It is less e4pensive than the EH( but replaces hu$idity for air pressure $easure$ent #rguably, #rguably, the +MP1B0 is also easier to use as it does not re/uire as finicky data strea$ ti$ings (his is a 3D device (he I address of the the device is 0x66 (he I co$$ands to read the device are described in detail in the the data sheet #t a high level, we read out a series of P"M registers and then ask for both the te$perature and pressure (he values returned for these these later values need to the$ be arith$etically co$bined with the P"M registers using so$e e/uations and the result will be two outputs # te$perature in  and an air pressure in Pa (he pin out of the device isPin

1abel

Description

1

/./

=ot used

2

+5%

I2C +5%

/

+C8

I2C +C8&  



*=5

*=5

$

#CC

/./#

nce connected, we can run i2cdetect to list the devices on the I bus and we should find the +PM1B0 at 0x66 $ sudo i2cdetect -, 2 0 1 2 3 4 ! H 6 G # a b c d e f 00 -- -- -- -- -- -- -- -- -- -- -- -- -Page 2$<

10 20 30 40 !0 H0 60

--------

--------

--------

--------

--------

--------

--------

------66

-------

-------

-------

-------

-------

-------

-------

-------

ee also•

Eata sheet

•

parkfun L +MP1B0 +aro$etric Pressure ensor Hookup

•

+MP1B0 I Eigital +aro$etric Pressure ensor 

•

?ohnny) ?oh nny)Five Five L +aro +aro$ete $eterr L +MP1B +MP1B0 0

•

?ohnny) ?oh nny)Five Five L (he (her$o$e r$o$eter ter L +PM1B +PM1B0 0

*otion detectors – Passi'e Infrared %ensor /PI"0 !hen you walk towards the door of your local large grocery store, you probably find that the doors slide open by the$selves (here has to be so$e s$arts so$ewhere that detects your presence and knows to operate the $otors that slide the the doors open (his device is called a Passive Infrared ensor 8H)"2019 and is one of the si$plest si$plest devices to use (hey can be found on e+ay for about ;00 or less

(hese devices have two s$all potentio$eters on the boards boards ne is used to ad6ust the sensitivity 849 and the other is used to ad6ust the delay delay ti$e 8(49 before it resets (here is also a 6u$per that controls whether or not the the detection is *repeatable* +y this we $ean $ean that if there is a detection of presence, the signal goes goes low to high ow, what happens if there is (I:: presence after after the reset ti$e In non)repeatable $ode, the signal signal goes low after the reset ti$e and will then go high again 8possibly i$$ediately9 when presence detection is $ade !ith repeatable $ode, the signal $ay ( go low after the reset ti$e IF there there is still presence detected nly after a reset ti$e #E the change to no further detection of presence will the signal go low again o$e $odules have 6u$per pins wired, others 6ust have pads which can be soldered Page 2$9

In addition to these slightly larger $odels, there is also the H)"202 $ini PI" $otion sensor

(heir wiring could not be si$pler (hey have three pins labeled K2v, AE and ut !hen $otion is detected within the sensor range of the device, the output pin transitions fro$ low to high and stays there until a configurable delay ti$e says that is desirable to go low again (here isn't $uch $ore to say about the$ than this +ecause they have no input re/uire$ents other than power, and the output can be voltage divided fro$ 2D to 33D for HIP, all we need do is choose a API pin for input and wire it up !e can then poll or trigger on a value change on the pin and we will have learned that there is $ove$ent within the range of the device ee also•

!ikipedia L Passive infrared sensor 

•

H)"201 PI" Motion Eetector datasheet

Ultrasonics – HC6%"=: I$agine that we wish the HIP to discover the distance to an ob6ect, how $ight we go about achieving that ne way is through the use of an ultrasonic trans$itter . receiver (hese devices are very cheap and also very easy to use (he principle of operation is very si$ple ven though when so$eone speaks to you, it feels like their voice reaches you instantly, this isn't actually the case ound $oves through the air at a relatively slow rate 8relative to light for e4a$ple9 (he appro4i$ate speed of sound is 3C0 $eters.second (hus if you were 3C0 $eters away, a loud sound would take 1 second to reach you If you were @B0 $eters away, the sound would take two seconds to reach you Nou probably recogni%e that this is what happens in a thunder stor$ If you see a lightning flash, it can be $any seconds before you hear the thunder (his is because light travels 'ery fast but sound travels $uch slower (he H)"0C device e$its a pulse of sound but at such a high fre/uency, our ears can't hear  it !hen the sound is e$itted it travels outwards away fro$ the device If there is an ob6ect in its path, so$e of that sound is reflected back the way it ca$e & back towards the H) "0C If the H)"0C receives an echo fro$ a previous pulse, it indicates that on an output pin (he H)"0C has a high resolution ti$er within it that starts when the output is trans$itted and stops when an echo is received (he duration of the ti$e between trans$ission and echo response is output to us !e now have learned the duration of ti$e between when a sound was e$itted and the echo received ince we know the speed of sound and we know Page 2)0

a ti$e period, we now know how far the sound wave traveled ince the distance it traveled is the distance to a re$ote ob6ect and back again, if we halve the distance & we have learned the distance to that ob6ect peed of sound is 3C0< $.s 83C0< Z 3<3=01 inches.sec9 all this Dsound

If (echo is the ti$e for echo response thend=

( T echo ×V Sound ) 2

 #lso the e/uation for e4pected (echo lengths is given byT echo =

2

×d

V sound

For e4a$pleDistance

ime

1c

2 Y 0.01 F /0 N 0.0$< secs N $9 usecs

10c

2 Y 0.1 F /0 N 0.$9 secs N $90 usecs

1

2 Y 1 F/0 N $.9 secs N $900 usecs ?$.9 secs@

(here are so$e i$portant li$itations in using an ultrasonic distance sensor (he distance is calculated by reflecting a sound wave off a re$ote ob6ect and receiving the response (his works great if the target ob6ect is perpendicular to the source of the sound However, if the target ob6ect is at an angle to the source then the results can be either off or the target $ay si$ply not be detected (o see why this is, consider a wall at an angle greater than C2  to the source !hen the sound wave strikes the wall, rather than be reflected back to the source, it will be reflected off so$ewhere else If we re$e$ber back to a bouncing ob6ect fro$ high) school, the angle of incidence e/uals the angle of reflection o a perfect response will be found when the sound wave strikes the ob6ect at e4actly <0  #nything else and we have introduced either error or a $issed response

Page 2)1

(he H)"0C is a C pin device  cc L (he input voltage is 2D  *rig L Pulse to trigger a trans$ission & $ini$u$ of 10 $icroseconds  Eco L Pulses low to high to low when an echo is received !arning, this is a 2D output  <&d L Around end a $ini$u$ of a 10 $icroseconds pulse to the *rig pin 8low to high to low9 :ater, the Eco will go low.high.low (he ti$e that Eco is high is the ti$e it takes the sonic pulse to reach a back)end and bounce back +ecause the cho response is a 2D signal, it is vital to reduce this to 33D for the HIP # voltage divider will work ee also•

Eatasheet

•

Nou(ube- #rduino (utorial- 7ltrasonic ensor H "0C distance $eter with a okia 2110 :E display

n"&9:(=@ networking ote- (his section is not co$plete and is likely to be a place holder until we have PI (he n"FC:01 is an ultra cheap co$$unication device It allows one to trans$it and receive data over large distances 8hundreds of feet9 It trans$its and receives packets between like devices Eo not confuse it with !iFi or +luetooth Nou can trans$it fro$ one n"FC to another n"FC but not to anything else (here are a nu$ber of reasons to consider this device for pro6ects over others First is the e4tre$ely low cost #n instance of the device can be picked up for less than a dollar econd is the peer)to)peer nature of the devices (here does not need to be a $aster.slave relationship in the story In fact, two or $ore devices can e4change packets with each other without any of the$ acting as controllers (here are occasions where this is e4actly what is needed Page 2)2

(he device operates on 33D and uses PI as a protocol (he pin)out on the n"FC:01 isPin

Description

#cc

/./#

*=5

*round

:I+3

+PI :aster InF+lae 3ut.

:3+I

+PI :aster 3utF+lae In.

+C&

+PI +yste clock.

C+=

+PI Chi! +elect – 6nable the deice ?actie lo"@.

C6

'E or TE ode. The 5ata sheet calls this Chi! 6nable "hich sees an a"ully strange nae or a counication ode selector.

I'

:askable interru!t.

ee also•

ordic e$i L Ho$e Page

•

Eata sheet

•

:a$p witch

•

(utorial- 7ltra :ow ost C AH% ! ireless (ransceiver with the F"EM +oard

•

?ulian Ilett V1

•

"FC:01 ) How (o

•

 #dding a n"FC:01 to a breadboard or stripboard

•

(utorial 0- verything Nou eed to 5now about the n"FC:01 and Mi"F)v

•

np$ nrf  L n"FC:01 library for ode6s and "aspberry Pi

.sing the (rduino (P+s  #n #rduino library for the n"FC is available called "FC (his library is highly active and well docu$ented It appears to be a fork of the "FC library originally created by Manicbug It has a detailed set of docu$entation including descriptions of all the class #PIs

 # typical flow would be-

Page 2)/

(24 radio.:E7P=> :)>7P=>Y radio5begi&.Y radio5setP+Ae/el.(247P+7AD'Y radio5ope&'riti&gPipe.address*@Y radio5ope&(eadi&gPipe.1address(@Y  *o be a recei/er 555 radio5startAiste&i&g.Y

(o stop being a receiver, callradio5stopAiste&i&g.Y

ince there are only two $odes, a receiver and a trans$itter, when one stops being a receiver, one i$$ediately beco$es a trans$itter (o deter$ine if there is data available to receive, callradio5a/ailable.

(o read data, we can callradio5read.address le>Y

(o write, we can callradio5%rite.address le>Y

(he library co$es with so$e sa$ples

•


+efore the library can be used, an instance of it $ust be constructed (he constructor looks as follows(24.cePi& csPi&

(he #rduino pins for ce and cs need not be fi4ed and hence we $ust instruct the library as to which pins we actually used (ake care that when an instance is created you specify the pins in the correct order as there is no guard against that +efore any other functions can be called, we $ust call begi&. (his perfor$ the initiali%ation of the device plus sets defaults for $any of the operational para$eters very device has an address associated with it (his allows a trans$ission fro$ one source device to be addressed to a specific destination device !hen a trans$ission occurs, devices other than the one with the $atching address will ignore the trans$ission (he device re/uires the si%e of the address to be supplied and fi4ed (he allowable address si%es are 3, C or 2 bytes (he default is 2 bytes (he si%e of the address can be changed with the set+ddress'idt. $ethod however you are unlikely going to want to change the default value Nou $ust re$e$ber to supply the full data for the address For e4a$ple, don't set an address of *123* when the address si%e is 2 bytes as your device address will beco$e *123`J`J* and you will likely waste ti$e trying to find out why no data is co$ing to you  #t this point, we $ust consider what we are going to do with the device fro$ here on (he device has two $odes of operation It can trans$it data or it can receive data but it can't do Page 2)

both si$ultaneously :et us look first at being a trans$itter First we create a *pipe* over which the data will flow !e supply the address of the destination ope&'riti&gPipe.co&st u&itG7t Raddress

For e4a$pleu&itG7t address 9 "1>ode"Y ope&'riti&gPipe.addressY

!e are now ready to actually trans$it so$e data bool %rite.co&st /oid Rdata ui&tG7t le>Y

(his $ethod will trans$it the data pointed to by the data pointer for the nu$ber of bytes supplied in length (here is a $a4i$u$ si%e as specified by the getPa,load)iCe. $ethod and you should not e4ceed that (he $ethod will block until the data has been trans$itted or the trans$ission re/uest has ti$ed out (he ti$e out is short, about =0$s so you won't block for long 7pon return fro$ the $ethod call, we can deter$ine whether the trans$ission was successful or if it failed # return value of true $eans we succeeded while false $eans as failure (he device has a $a4i$u$ trans$ission si%e that is 3 bytes Nou can not trans$it packets larger than this (he default $a4i$u$ trans$ission set in the library is 3 bytes which is the $a4i$u$ that the device will per$it Nou can change this with the setPa,load)iCe. $ethod but it is unlikely you will need that function i$ply re$e$ber that we can not ever send a payload si%e greater than 3 bytes (he other $ode of the device is that of a receiver where we actually listen for inco$ing data  #s $entioned, the device can either be in trans$it $ode or receive $ode (o receive inco$ing data, we need to supply the address of the device fro$ which we are e4pecting inco$ing data to arrive !e do this using the ope&(eadi&gPipe. $ethod ope&(eadi&gPipe.ui&tG7t &umber co&st ui&tG7t Raddress

nce we have specified the address of the trans$itting device we will receive data fro$, we can start actively listening using the startAiste&i&g. $ethod hould we wish to end listening $ode, we can call the stopAiste&i&g. $ethod which will return us to trans$ission $ode nce we have entered listening $ode, we can ask the library if there is data available for us to read (he $ethod for this is available89 If there is data available, the return value is true and false otherwise (o actually read the data that was received, we can use the $ethod called read. read./oid Rbuf ui&tG7t le&

(his $ethod supplies a buffer into which the received data will be stored (he length of the buffer is also supplied  # debug file called pri&t?etails. is provided which logs the state of the n"FC to the Page 2)$

stdout In order to use this one $ust•

Include pri&tf5J

•

all pri&tf7begi&.

!hen the pri&t?etails. function is then called, a status of the n"FC is written to the erial port (his can be a powerful tool for debugging proble$s Here is an e4a$ple of the output)*+*8) 9 (@7+??(7P0-1 9 (@7+??(7P2-! 9 *@7+??( 9 (@7P'7P0-H 9 E>7++ 9 E>7(@+??( 9 (7:; 9 (7)E*8P 9 :D>=< 9 ?L>P?E+*8(E9 ?ata (ate 9 odel 9 :(: Ae> 9 P+ Po%er 9

0x0e (@7?(90 *@7?)90 +@7(*90 (@7P7>D96 *@78AA90 0x004!444f4e 0x004!444f4e 0xc3 0xc4 0xc! 0xcH 0x004!444f4e 0x20 0x20 0x00 0x00 0x00 0x00 0x3f 0x02 0x4c 0x03 0x0f 0x00 0x00 1BP) &(24A01] 1H bits P+7AD'

ee also•

Aithub pro6ect

•

Pro6ect +log

•

Foru$ thread

$raphic 48uali7er   #n I called the MAU= is a graphic e/uali%er I It can operated at 33D or 2D If we provide it an audio input signal, it will analy%e the signal into = discrete fre/uency bands of @3H%, 1@0H%, C00H%, 15H%, 25H% and @25H% (he I is supplied in an B pin configuration with-

Page 2))

Pin

unction

Description

1

#55%

/./$# !o"er su!!ly

2

#++%

=egatie

/

3UT

:ulti!leed 5C 3ut!ut. This is an analog out!ut alue.



+T'3B6

Channel selection

$

I=

%udio in!ut

)

*=5

,

'6+6T

'eset. % high resets the ulti!leor4 lo" enables the strobe.

<

C&I=

Clock  

ince the output of this device is an analog signal and our Pi doesn't have an in)built analog to digital converter, we will have to co$bine this I with an #E if we wish to consu$e the generated values back into our Pi ee also•

Eatasheet

*icrophone inputs !e can attach a $icrophone to a sound card but what if we don't have a sound card M what choices do we have Microphones can be found very cheaply (he going rate is about ;0C0 each on e+ay (he $ost useful $icrophone style for us is the electret style

&* "adio (he I called (#2=@= provides FM fre/uency radio receiver which is digitally controlled via the I bus (he address of the device is 0xH0 Modules for this I can be found on e+ay for about ;C (he device can be powered fro$ either 33D or 2D (he reception fre/uency is fro$ =@MH% to 10BMH% (he pins on it are-

Page 2),

Pin

Description

1

+5%

2

+C8

/

*=5 – should be grounded



=C

$

#CC – /./# – $#

)

*=5 – should be grounded

,

8et 3ut

<

'ight 3ut

9

*=5

10

%ntenna

ontrol of the device is by writing C0 bits 82 bytes9 of infor$ationByte 1 ,

:UT6

:ute controlK • 1 – %udio is uted • 0 – %udio is not uted 5eaultK 0

)

+:

+earch odeK • 1 – +earch ode on • 0 – +earch ode o  5eaultK 0

$K0

P88Q1/K
Byte 2 ,K0

P88Q,K0R

Byte / ,

+U5

+earch u!Fdo"nK • 1 – +earch u! • 0 – +earch do"n 5eaultK 1

)K$

++8Q1K0R

5eaultK 0b01



H8+I

5eaultK 0

/

:+

:ono or stereoK • 1 – :ono • 0 – +tereo 5eaultK 0

2

:'

:ute rightK • 1 – 'ight channel uted • 0 – 'ight channel not uted 5eaultK 0

1

:8

:ute letK

• •

1 – 8et channel uted 0 – 8et channel not uted 5eaultK 0 0 Byte 

Page 2)<

+7P1

5eaultK 0

,

+7P2

5eaultK 0

)

+TBG

5eaultK 0

$

B8

Band liitsK • 1 – Aa!anese • 0 – U+F6uro!e 5eaultK 0



ET%8

5eaultK 1

/

+:UT6

+ot uteK • 1 – +ot ute is on • 0 – +ot ute is o  5eaultK 0

2

HCC

5eaultK 0

1

+=C

+tereo noise cancelingK • 1 – +tereo noise canceling is on • 0 – +tereo noise canceling is o  5eaultK 0

0

+I

5eaultK 0

,

P88'6-

5eaultK 0

)

5TC

5eaultK 0

$K0

=F%

5eaultK 0

Byte $

ee also•

Eatasheet

•

 #rduino L (#2=@= "adio

•

Aithub- andykarpov.(#2=@=

(4- ;6%egment displays (he =)eg$ent display is an :E device that is co$posed of = line seg$ents that can be arranged to display nu$bers (here is also an eight :E that is used to display a deci$al point (he $akeup of the seg$ents are shown in the following diagra$-

 #lthough a seven seg$ent display looks */uite dated* they should not be discounted If what one wants to do is show a nu$eric value that can be read fro$ a distance and which is very cheap to use, then this device $ay be 6ust perfect Page 2)9

It is co$$on to see =)seg$ent displays used in con6unction with the M#J=1< or M#J=1 Is (hese Is know how to drive up to eight $ultiple4ed =)seg$ent displays with data received over an PI bus #s such, HIP can send in an PI signal and these devices can easily display the results 7nfortunately at the ti$e of writing, HIP does not yet support PI ee also•

!ikipedia L even)seg$ent display

+pto isolators > +pto couplers If we are working with high voltages or working with electrically *noisy* devices, we want to keep these clear of the HIP's API headers # $is)wired high voltage will destroy HIP and noisy electrical lines will result in spurious signals on the data bus M neither of which are desirable ne solution to the proble$ is to separate the high voltage.noisy circuit fro$ the HIP circuit but this then leaves us the pu%%le of how the two circuits will interact with each other ne possibility is a $echanical relay but, being $echanical, if switched rapidly for too long, it will wear out In addition, it is acoustically noisy Finally, the switching ti$e 8the ti$e between a re/uest to open.close the circuit9 is large  #nother possibility for our pu%%le is the concept of the opto)isolator circuit #n opto)isolator is a device which has two pri$ary active co$ponents (hese are an :E and a light activated switch (hese are then $iniaturi%ed and encased within an I package (he result is a logical circuit that looks as follows-

(hese are available in both $odule and discrete co$ponent for$ (he following i$age shows a C channel version available for under ; (his device is based upon the (:PB1 I (he switch ti$e for this is less than 2 Zs

Page 2,0

(he pin)out of the $odule is3UT1

=C

3UT2

I=1

3UT/

I=2

3UT

I=/

H#CC

I=

H*=5

*=5

Here is a high level sche$atic-

(he notion is that <>? is wired to the Pi <>? =>1, =>2, =>3 and =>4 can be wired to API output pins of HIP (his for$s the Pi side of the circuit n the other side of the circuit, we provide a separate source at ;:: and ;<>? ote that ;:: is not to be greater than CD  # high on =>1 produces a high on D8*1 and a low on =>1 produces a low on D8*1 M effectively D8*x 9 =>x M but physically decoupled fro$ each other and hence no noise leakage between the$ thers are the P13 (he switch ti$e on this device is less than 0Zs

ote that the internal :E is driven at between 1 and 1C volts (his $eans that it is not tolerant of either 33D or 2D so take care to use a voltage divider to properly control the input

Page 2,1

Input

R, 89:ere R+ ; ,-<=

/./#

?/./1./@  10000F1./ N 1$&  

$#

?$1./@ Y 10000F1./ N 2<.&  

(he P13 has a *dot* on its top left surface to $ark orientation (he pin out thus aligned is865 %node

Transistor Collector  

865 Cathode

Transistor 6itter  

For driving high current load devices, consider using a sufficiently powerful transistor and having the output of the opto isolator drive the switching of the transistor which is connected to the final load ee also•

(:PB1 ho$e page

•

(:PB1)C Eata heet

•

harp P13 Eata heet

•

:ogic :evel hifting

C-:=A@ – -igital switches Many of the previous hardware integration e4a$ples have de$onstrated how to configure the Pi with $odules that are the$selves pre)built circuits Here we are are going to discuss a single raw integrated circuit called the EC021 fficially, it is described as an analog $ultiple4er.de$ultiple4er & however the$ there are so$e big words !hat it really is is a digital switching circuit :ogically, you can think of it in ter$s of the following diagra$-

(here is a co$$on pin fro$ which data can be either read or written (hat pin will be connected internally to one of the channel pins 80 through =9 (he selection of which pin is governed by the digital signals on #, + and  (he 3 bits of infor$ation there select the Page 2,2

corresponding channel Finally there is an inhibit pin which if set will prevent any connection between the input and the output (he connections between the co$$on pin and the channel pin is fully analog & it can be used to provide a digital signal or an analog signal & in either direction !ith this background, how then $ight we use such an I I$agine we only have one #nalog to digital convertor input on our Pi but we want to take readings fro$ $ultiple sensors !e could switch between each of the sensors taking a reading before $oving onto the ne4t (he EC021 is very cheap, under ;0C0 an instance as found on e+ay Its physical pin layout isPin

Description

1

Channel [

2

Channel [)

/

Coon In or 3ut



Channel [,

$

Channel [$

)

Inhibit

,

#ee ?*round@

<

#ss ?*round@

9

In!ut C

10

In!ut B

11

In!ut %

12

Channel [/

1/

Channel [0

1

Channel [1

1$

Channel [2

1)

#dd ?Oe@

ee also•

(e4as Instru$ents L EC021 data sheet

•

Nou(ube- C000 eries :ogic Is- (he C021 B)channel analog $ultiple4er.de$ultiple4er I

%oftware -efined "adio – -VB6T "ecei'er  !e are fa$iliar with the concept of a radio receiver !e find these in our car to listen to our radio stations However, radio fre/uency is a big thing and there is all sorts of data whi%%ing over us 8through us9 (his takes us into a new category of hardware integration called oftware Eefined "adio or E" (here are a couple of leading Is on the $arket called the "(:B37 and "B0( that have been cheaply $odulari%ed (hese $odules plug into a 7+ port and provide radio signal decoding (hese can be bought for about ;< or under Page 2,/

My e4perience with plugging the device directly into HIP has been very poor !hen I plug it directly into the 7+ port, the whole HIP shuts down I believe it is because the device is drawing too $uch current !hen I plugged the receiver into an e4ternal 7+ hub and plugged the hub into HIP, all started working as adverti%ed oftware defined radio hip sets "B0(K"(:B37 !hen plugged into a !indows 10 device it shows up as an "(:B3B7HEI" !hen testing on windows, there appears to be a nu$ber of drivers-

•

@C130C00<

•

@C12101 L 01)02)1

•

@C1B0101 L 013)0B)01

(he physical connector on these dongles is known as *MJ* ee also•

"(:B37 L ED+)( Ee$odulator 

•

http-..answers$icrosoftco$.en)us.windows.foru$.windowsT10)hardware.realtek)rtlB3u)tv)usb) dongle)not)working)with.dC@Cf@eC)C@a)Ccde)bbee)0d=0@2
•

http-..wwwrtl)sdrco$.

•

"(:B3u L "B0( D "(:B3u L "B0(

(D-" Decoding  #irplanes trans$it transponder signals called #E)+ 8#uto$atic Eependent urveillance L +roadcast9 (hese can be received and decode with a oftware Eefined "adio 8E"9 (he broadcast fre/uency is 10<0MH%

 #fter plugging in the ED+)( dongle, we find that it will show up as a 7+ device with vendor code 0bda and device code 2G3G For e4a$ple$ sudo lsusb Bus 001 ?e/ice 00! =? 0bda2G3G (ealtek )emico&ductor :orp5 (*A2G3G ?B-* Page 2,

(he drivers for this are part of the package called * rtl-sdr* and should be installed with$ sudo apt-get i&stall rtl-sdr

If you are co$piling code, you will also need * librtlsdr-de/* (his can be installed with$ sudo apt-get i&stall librtlsdr-de/

!ith the environ$ent ready, we now need so$e software to decode the data #n e4cellent application called dump10#0 810<0 because of 10<0MH%9 is available e4t we download the AI( source for du$p10<0 and co$pile it (his will also re/uire the *libusb-150-0-de/* package$ sudo apt-get i&stall libusb-150-0-de/

(hen we can run du$p10<0 I like the co$$and$ sudo dump10#0 --i&teracti/e

If we run the progra$ with the --&et flag, then we can point a browser to it at-

ttpost&ameJG0G0 and we will be presented with a Aoogle $ap showing the data For progra$atic access, we also have so$e options (he du$p10<0 progra$ listens on port 30003 for parsed data # ode6s $odule is available that can parse this data 8see Aithubwise$an.node)sbs19 it is available as the PM package called * sbs1* (he for$at of the data can be seen herehttp-..woodairnet.+.#rticle.+arebonesCTocketTEataht$ ne particularly useful $echanis$ is to use the ode)"E (P input node to target the Page 2,$

output of dump10#0 !e can ask for strea$s of strings ter$inated by a newline (his will generate one record per event received over #E)+ (he configuration of such a node will be-

!e can then in6ect that into a D node to parse the co$$a separated data-

(he first colu$n is * col1* which will always be the constant * )<* (he ne4t colu$n, *col2* is the $essage type 8nu$eric9 and this beco$es i$portant Page 2,)

 #n e4a$ple flow $ight be-

(o $ake this activity easier, a custo$ #E)+ ode)"E node has been developed that takes as input an + $essage and returns a populated ?avacript ob6ect (he node can be found herehttp-..flowsnoderedorg.node.node)red)contrib)ads)b If you get the flight nu$ber of an aircraft and are curious to know where it is going to or fro$, you can look it up at flightradarC herehttps-..wwwflightradarCco$.data.flights ee also•

"(:)E" (7("I#:- H#P #E)+ #I""#F( "#E#"

•

du$p10<0 $essage data for$at descriptions

•

https-..githubco$.Malcol$"obb.du$p10<0

•

https-..githubco$.antire%.du$p10<0

Bluetooth tracker – iTag (he i(ag is a cheap little device 8;);C on e+ay9 that is a +luetooth device Its purpose is to for$ a connection with a +luetooth $aster If the connection is subse/uently lost, the device starts beeping In addition, the device can receive a *ping* fro$ the $aster to instruct it to start beeping In all these cases, it acts as a useful device to help you locate it should it get lost ow i$agine connecting it to your keys, pet, kid or other loose)able thing and now we have a potential of either being notified that it is out of range or else it will beep to say *help $e*

If we use +luetoothctl and scan for new devices with an i(ag in range, we will find it If we pair with it and then ask for the info of the device, we will findPage 2,,

SbluetootTF i&fo 4!1#14G0 ?e/ice 4!1#14G0 +lias --4!-1#-14-G0 +ppeara&ce 0x03c1 =co& i&put-ke,board Paired ,es *rusted &o Blocked &o :o&&ected ,es Aegac,Pairi&g &o 88=?
.00001G00-0000-1000-G000-00G0!f#b34fb .00001G02-0000-1000-G000-00G0!f#b34fb .00001G0f-0000-1000-G000-00G0!f#b34fb .0000ffe0-0000-1000-G000-00G0!f#b34fb

ow if we disconnect fro$ the device, the device will start beeping If we reconnect or press the button on the device, it will stop beeping (he services e4posed by the device include-

•

Aeneric #ccess L 041B00

•

I$$ediate #lert L 041B0

•

+attery ervice L 041B0f 

ow let us turn our attention on how to control this device fro$ HIP First, we need to find the address +luetooth :ow nergy 8+:9 address of our i(ag witch on the i(ag 8it will beep once9 ow fro$ the ter$inal, enter$ sudo citool lesca& AE )ca& 555 4!1#14G0 .u&k&o%&

opy this address into a notepad or other buffer, we will need it later ow we can start to perfor$ work against the device tart up *gatttool* $ sudo gatttool --i&teracti/e S TSAETJ

nce started, let us now connect to our deviceS TSAETJ co&&ect 4!1#14G0 +ttempti&g to co&&ect to 4!1#14G0 :o&&ectio& successful S4!1#14G0TSAETJ

If we now issue a disconnect, we will find out device starts to beep !e can stop the i(ag beeping by either pressing the button on its top or else re)connecting #nd we have now perfor$ed the first of our tests +y connecting HIP to the device and then disconnecting, we caused the device to beep (he ne4t thing we can do is to cause the device to beep by sending it a co$$and 7nderstanding this recipe assu$es that you have studied +: specifications and it is a bit deep, however I'll describe the high levels as we go along !ith gatttool running and connected, issue the co$$and called * primar,*S4!1#14G0TSAETJ primar, Page 2,<

attr attr attr attr

a&dle a&dle a&dle a&dle

0x0001 0x000H 0x000# 0x000c

e&d e&d e&d e&d

grp grp grp grp

a&dle a&dle a&dle a&dle

0x000! 0x000G 0x000b 0x000e

uuid uuid uuid uuid

00001G00-0000-1000-G000-00G0!f#b34fb 00001G0f-0000-1000-G000-00G0!f#b34fb 00001G02-0000-1000-G000-00G0!f#b34fb 0000ffe0-0000-1000-G000-00G0!f#b34fb

otice the *77IEs* on the right (he 77IE that starts with *1B0* is the specification for an *I$$ediate #lert* service otice also that it has *handles* in the range of 04< to 04b e4t run the co$$and to e4a$ine the handlesS4!1#14G0TSAETJ car-desc 0x# 0xb a&dle 0x000# uuid 00002G00-0000-1000-G000-00G0!f#b34fb a&dle 0x000a uuid 00002G03-0000-1000-G000-00G0!f#b34fb a&dle 0x000b uuid 00002a0H-0000-1000-G000-00G0!f#b34fb

Fro$ here we see that the handle at 04b corresponds to the characteristic of the service known as a0@ which is the co$$and to send an alert +y e4peri$entation, I have found that sending *10* causes the device to start beeping and sending *00* cause it to stop beepingS4!1#14G0TSAETJ car-%rite-cmd 0xb 10 S4!1#14G0TSAETJ car-%rite-cmd 0xb 00

Finally, when the device is silent, if we click the button on the top of the i(ag, notice that we receive an indication.event.notification that so$ething happened>otificatio& a&dle 9 0x000e /alue 01

(hat opens up a wealth of possibilities ow i$agine  #nd now we have seen the functions available to us I$agine we wanted our HIP to do so$ething fro$ a distance # single click on our i(ag could be a start signal and a second click a stop signal For e4a$ple, taking a picture ee also•

Nou(ube- HIP (utorials- Interfacing with i(ag

•

How to use the i(ag +luetooth tracker 

•

+luetooth

"eal time clocks !hen we start a HIP, it doesn't know what the real world clock ti$e is !e can tell it once booted but even then, once we power it off, it will forget again when ne4t restarted If the HIP is connected to the Internet, it can learn the real ti$e by using a network ti$e protocol which $eans that it connects to an e4ternal server that does know the real ti$e and asks it for  the answer However, if our HIP is not connected to the Internet and is network isolated, by default, it has no $echanis$ to know the current ti$e (his is where we can add a real)ti$e) clock 8"(9 $odule # real)ti$e clock $odule is a s$all piece of electronics that contains a battery and is taught the current date and ti$e +ecause it has an on)board battery, it can re$e$ber the ti$e even when the HIP is powered off !hen the HIP boots, it can be configured to ask the "( $odule for the current date.ti$e and use that fro$ then on (here are $any "( $odules available but one of the $ore prevalent is the E130= Page 2,9

(hese can be picked up on e+ay for about ;1 (he "( uses battery backup when not powered (his is a standard "03 battery type !hen inserting the battery, it is Kve down !hen soldering on header pins, think through how you will $ount the board when co$plete It $ay be that you want to solder the header pins such that you can easily access and replace the battery once attached to your P+ or strip board (his device provides a real ti$e clock capability that includes hours, $inutes, seconds, $onth, day of $onth, day of week and year Month calculations including leap year support are also acco$$odated Interestingly, it also provides 2@ bytes of non)volatile "#M for user storage (he device uses I for co$$unication  =oteK Beore !lugging your board to the CHIP4 reali;e that this board is a $# odule. I you connect $# to the CHIP\s *PI3 !ins bad things can ha!!en because they are /./# !ins. The I2C !rotocol uses !ullu! resistors to bring the +5% and +C8 lines high by deault. I "e "ere to look at the scheatic diagra o this odule "e "ould ind that resistors '2 and '/ are !ullu ! resistors. Unortunately4 "e hae t"o !robles. -irst is that the CHIP already !ulls u! the !ins and secondly the odule !ulls the high to a $# line "hich is too uch or the CHIP. The solution is to !hysically reoe these t"o resistors ro your odule beore use. The resistors are clearly arked on the board as '2 and '/ and carry the ark //2 ?/./k@.

(he boards have 2 pins on one side = on the other (he 2 side is duplicated on the = side Pin

1abel

Description

1

5+

5+1
2

+C8

I2C clock.

/

+5%

I2C data line.



#cc

#cc ?$#@.

$

*=5

*round.

Pin

1abel

Description

1

+

+uare "ae out!ut.

2

5+

5+1
/

+C8

I2C clock.



+5%

I2C data line.

$

#CC

#cc ?$#@.

)

*=5

*round.

,

B%T

Battery oltage

Page 2<0

Here is an e4a$ple sche$atic for wiring-

nce plugged in, we will see the "( at I address 0xHG$ sudo 0 00 10 -20 -30 -40 -!0 !0 H0 -60 --

i2cdetect -, 2 1 2 3 4 ! -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --- -- -- -- --

H ---------

6 ---------

G # -- --- --- -3G --- --- -68 --

a --------

b --------

c --------

d --------

e --------

f --------

nce connected, it is ti$e to start looking at the software side of the house HIP provides a kernel level $odule to integrate with the clock that is enabled by default e4t we $ust tell the I subsyste$ that a "( clock is present and tell it what I address it is present on !e do that by echoing *ds1306 0xHG* into the file s,sclassi2cadapteri2c-2&e%7de/ice For e4a$ple$ sudo bas F eco "ds1306 0xHG" J s,sclassi2c-adapteri2c-2&e%7de/ice

Page 2<1

Following this we will find so$e new device driver files up in de/ a$ely we will find de/rtc and de/rtc0 !e can now ask the %clock what ti$e it thinks it is with$ sudo %clock --so% *ue 0! a& 201H 062422 P :)*

-051!H3G2 seco&ds

If the clock has not been set, then it will be so$e odd ti$e back in the past If so, we can set the hardware clock fro$ the current date.ti$e with$ sudo %clock --s,stoc --debug --&oadIfile -utc %clock from util-li&ux 252!52 8si&g te de/ i&terface to te clock5 +ssumi&g ard%are clock is kept i& 8*: time5 1460!041245!00000 is close e&oug to 1460!041245!00000 .05000000  05001000 )et (*: to 1460!04124 .1460!04124 ] 0Y refs,stime 9 1460!041245000000 )etti&g ;ard%are :lock to 162204 9 1460!04124 seco&ds si&ce 1#H# ioctl.(*:7)E*7*=E %as successful5

and if we re)run %clock --so% we will see the proper ti$e #t this point, the %clock is set and keeping real)ti$e !hen ne4t the HIP reboots we need to instruct it to read the ti$e fro$ the %clock which will have kept it for us and sync the syste$ ti$e fro$ that value (his $eans that HIP has to re)associate the hwclock with I and then e4ecute%clock --ctos,s

(his will synchroni%e the %clock back to the  date.ti$e ee also•

:ogic :evel hifting

•

Nou(ube- HIP (utorials- "eal (i$e lock

•

(utorial L 7sing E130= and E331 "eal)ti$e lock Modules with #rduino

•

Ma4i$ integrated datasheet

•

$an8B9 L hwclock

rduino I-4 on CHIP (he #rduino IE is an application and co$pilation environ$ent for building #rduino binaries and deploying the$ on the #rduino fa$ily of processors !e co$$only think of co$piling  #rduino apps using the #rduino IE on Ps but now we can co$pile the$ on HIP If we visit the #rduino software download page, we will find a binary for :inu4 #"M eehttps-..wwwarduinocc.en.Main.oftware !e should download this into our HIP ho$e directory !e will end up with a file calledardui&o-15H511-li&uxarm5tar5x/

!e can e4tract this using the * tar* co$and$ tar -x/f ardui&o-15H511-li&uxarm5tar5x/ Page 2<2

(his will take a few $inutes to co$plete (he result will be a new directory called * ardui&o15H511* hange into that directory and we are now ready to launch the IE "un the co$$and$ 5ardui&o

after a $inute, the IE will launch and you are now s/uarely in the world of building #rduino based applications

4lectronics ne of the key stories of the HIP is that we can use it to interact with the real)world through a variety of electronics devices connected to its headers (hankfully, we don't have to be rocket scientists or electrical engineers in order to get this going (here are $any free sources of knowledge on these topics on the Internet including step by step tutorials However, there are certain ite$s that one would not nor$ally hear about when working in the HIP that are related to electronics that I feel are of real value for you to understand ee also•

Page 2
:earning about lectronics

ttaching your Chip to circuit boards HIP has two headers called 713 and 71C both of which are C0 pin fe$ale headers ow i$agine that you want to build a circuit and attach your HIP to that circuit How then do you achieve that task ne way is to obtain so$e $ale.$ale C0 pin headers (here are co$$only known as *IE drive gender changer adapters* because of their co$$on usage pattern

If we solder a set into our P+ or perf)board then the other end will fit into the HIP +e 'ery careful with polarity If you set the HIP backwards into the header, you are very likely to da$age so$ething #lways $ark your circuit board with which end is which and check, check and double check your polarity before powering up  #n alternative to these $ale to $ail adapters are the following *long legged* headers-

(hese will e4pose an e4tension of the fe$ale headers for additional plugin

-rawing circuits and breadboards – &rit7ing (he fantastic open source package called Frit%ing 8wwwfrit%ingorg9 is one of the best packages available for both drawing circuit diagra$s as well as laying out breadboards nd users can create their own parts and share the$ via the Internet (he tool is very easy to use and provides an integrated circuit diagra$ editor plus a breadboard layout editor (he software is free to download atPage 2<

http-..frit%ingorg.ho$e. I reco$$end the use of Frit%ing for all but the $ost trivial of pro6ects +y using Frit%ing to visuali%e both a sche$atic and physical layout when it co$es ti$e to asse$ble a pro6ect, you will have a blue print to work fro$ It is te$pting to build a pro6ect going straight to the breadboard but resist that Invariably, you will spend $ore ti$e debugging than you would have spent drawing and then wiring In addition, you have an artifact in the for$ of the Frit%ing i$ages that can be referred to again and again over ti$e Ideally you will share these i$ages on the Internet for others to use If nothing else, when you co$e back to this pro6ect a $onth later you will have so$ewhere better to start with than any written notes you $ay or $ay not have taken ne of the true benefits of this package is that we are not constrained by the availability of parts (his takes a little ti$e and practice and one should be handy with the open source DA graphics editor called Inkscape ee also•

Frit%ing ho$e page

•

Inkscape

-rawing %chematics – -igi6!ey %cheme6it If one wishes to draw circuit sche$atics, the free Eigi)5ey che$e)it is hard to beat It re/uires no software installation on your P but instead runs e4clusively within a $odern browser It is intuitive and easy to use Nou should easily be able to learn it in $inutes

Page 2<$

ee also•

che$e)it

•

sche$aticsco$

-rawing %chematics and PCBs – Circuit*aker %oftware  #nother very worthy tool for consideration is ircuitMaker (his is a free !indows based tool that is super rich It does re/uire a native !indows install as opposed to being browser based but it does store its repository infor$ation in the cloud ee also•

ircuitMaker 

Using a logic analy7er  !hen you have built a circuit that includes your HIP and you run your application and the results are not what you are e4pecting, you are in trouble Nou need tools to diagnose your proble$ o $atter how carefully you e4a$ine your circuit with a $agnifying glass, you will not be able to see the bits and bytes flowing around !hat you need is a device called a logic analy%er o$$only, this is a device which plugs into your 7+ port of your P and allows you to attach connector wires to various places on your circuit (he nu$ber of concurrent wires you can connect is the nu$ber of channels available on the analy%er nce you have connected the wires, you run you application.circuit on the HIP !hile it is running, you start a recording on the P (he P and the logic analy%er now sa$ples the data on the wires and hence the data at the locations of where those wires are connected in your circuit (he sa$pling rate can be e4ceedingly high such that changes in signal values at a 100 nanoseconds or less can be detected (he data is recorded in the $e$ory of the P #fter a few seconds of sa$pling, you can stop the recording ow that you have accu$ulated the data, you take your ti$e and use the logic analy%er software to e4a$ine the results (his is usually in the for$ of a ti$e)line with a row per channel recorded (he row shows a line with values of low or high corresponding to the signal Nou can scroll along the line as well as %oo$ in or %oo$ out to show $ore or less detail for s$aller or larger periods of ti$e If you recorded $ultiple channels, you can see the relationships and ti$ing of signals as they change together or apart !hen working with protocols such as I or PI, a logic analy%er can be invaluable If you asse$ble a circuit and write an application and it isn't working as it should, you need so$e $echanis$ to perfor$ diagnostics (rying to debug PI or I without an analy%er is like trying to 6uggle with only one hand (here are a nu$ber of vendors of logic analy%ers on the $arket ne of the better suppliers is called aleae (hey $ake a sa$ple visuali%er called aleae :ogic that is e4tre$ely Page 2<)

elegant and perfor$s all the activities that one could sensibly want If one searches on e+ay, one can also find very cheap versions of analy%ers at around the ;10 price point Here is an e4a$ple screen shot captured using the e4cellent aleae :ogic tool-

ot only does this tool clearly illustrate the wave for$s, but it is also able to decode so$e of the well known protocols such as I and PI ee also•

aleae

•

!ikipedia L :ogic analy%er 

+'ercoming trepidation of using Integrated Circuits !hen it co$es to wiring a HIP to other $odules, $ost folks appear to be happy to do that when the $odules e4pose pins which are clearly labeled Plugging a pin on a device that is clearly labeled as *"J* or *(J* to the corresponding ter$inal on the HIP header see$s to be well within everyone's grasp However when we introduce integrated circuits, so$ething changes Integrated ircuits 8Is9 don't have friendly labels associated with their pins, they are s$aller and see$ to instill a degree of concern that isn't warranted

Page 2<,

Physically, the Is that we will be working with co$e as s$all, black devices with pins o$$only B or 1@pin but so$eti$es $ore and so$eti$es less (hey should be bread)board friendly $eaning that you can push the$ into a bread)board for testing (he biggest $ystery over the devices is how to connect the$ properly & and this is where the data)sheet of the device beco$es your greatest friend ach $anufacturer of an I produces a docu$ent called a data)sheet that describes in a lot of detail how to use it For hobbyists, that can see$ like too $uch detail (here are charts and graphs showing all kinds of infor$ation about its characteristics However, fro$ our perspective, what we really are looking for is the pin configuration nce we learn which pin perfor$s which function, we are well on our way to success !hen buying Is, $ake sure you understand the difference between EIP 8Eual in)line package9 which are Is with the pins in parallel rows that can be plugged into bread)boards (hese are also called *through the hole* co$ponents (he pri$ary alternative for$at is called surface)$ount (hese can not be directly used with bread)boards and for hobbyist and ease of tinkering considerations, should be discounted in favor of EIP !hen it co$es to asse$bling circuits and soldering the$ to a P+ or strip board, if the chip is e4pensive or you feel you don't want to co$$it it to 6ust one pro6ect, you can solder in an I socket into which the I can be inserted and subse/uently re$oved

(here are sockets for all the different EIP I di$ensions and they can also be found cheaply ee also•

!ikipedia- Eual in)line package

•

!ikipedia- List of integrated circuit package dimensions

(ogic (e'el %hifting !e have already read that the HIP API pins are 33D tolerant (his $eans that the $a4i$u$ input voltage $ust be 33D If you go higher than that, you are at risk for frying your  HIP +ut what if we have a peripheral device that outputs a 2D signal onversely, the $a4i$u$ output voltage on a HIP API is 33D If we feed that as input to a peripheral that is e4pecting a 2D input, there is no assurance that it will detect the signal correctly Fortunately there is a solution in a circuit called a logic level shifter (his circuit can convert a 33D signal to a 2D signal and can also convert a 2D signal to a 33D signal (he $odule takes as input Kve and ground of the high level and Kve and ground of the low Page 2<<

level and provides bi)directional switching

If you don't have access to such logic level circuits, an alternative solution is to create a voltage divider (his will protect 3D HIP inputs fro$ over voltage fro$ a 2D source (his is a si$ple circuit $ade with two resistors # higher voltage is provided to input than output and using a correct co$bination of resistors, the input voltage is proportionally scaled to the output voltage

(here is an e/uation available to usV out =

V i n× R 2  R 1 + R 2

 #s an e4a$ple of a solution to this e/uation, if D in is 2D and we want Dout to be 33D and choose 15] for " then &

=

3.3

  1000

 R 1 + 1000

×5

!hich evaluates to "1 having a value of 212 ] !e can use a higher value for "1 but not lower 4pressing the e/uation in a different order we have R 1=

(V i n−V out )× R 2 V out 

ee also•

parkfun L +i)Eirectional :ogic :evel onverter Hookup Auide

•

!ikipedia L Doltage divider 

Page 2<9

Transistors as switches If we consider that a API pin can produce a signal of high or low we see that the signal can be used to perfor$ work However there is a $a4i$u$ current that can be drawn fro$ any given I. pin If, for e4a$ple, we wished to attach a device to a pin which would draw $ore current than the pin is rated to supply, we $ay very easily da$age our HIP (his is where a transistor can co$e into play # transistor can be thought of as an electronic switch # transistor has three pins labeled e$itter, base and collector If a s$all current flows between base and e$itter a correspondingly higher current will be allowed to flow between collector and e$itter (here are two types of transistor we will co$e across called P and PP (he difference between the$ is whether or not the *switch* is triggered by a high signal or a low signal (he following is the sche$atic sy$bol for an P transistor or$ally we connect the e$itter to ground and a load between the collector and Kve If we then connect the base to the output of an I. pin 8through a resistor8, then when the pin goes high, a s$all current will flow between + and  and a $uch higher current will flow between  and 

For the other type of transistor 8PP9 whose sy$bol is shown in the following diagra$, the e$itter is usually connected to Kve and the collector to the load and then ground !ith the base pin connected to a API 8through a resistor9, when the base goes low, the s$all current flowing fro$ the e$itter through the base will be greatly a$plified as the current flowing through the e$itter to the collector

+y using a transistor, we are no longer directly drawing load through the API pin but instead si$ply using the signal present on the pin to energi%e the transistor o$$on transistors that can easily be obtained include-

Page 290

Name

ype

(tyle

2=/90 ?+ignal transistor@ – 200% a current

 =P=

T392

2=/90) ?+ignal transistor@

P=P

T392

P=2222

=P=

T392

TIP120 – $% a current

=P=

T3220

TIP12$ – $% a current

P=P

T3220

BC$, – 100% a current

=P=

T392

BC$$, – 100% a current

P=P

T392

2=/0$$ – 1$% a current

=P=

T3/

T3/

ee also•

3<0C Eata heet

•

3<0@ Eata heet

•

P Eata heet

•

(IP10 Eata heet

•

(IP12 Eata heet

•

+2C= Eata heet

•

+22= Eata heet

•

Nou (ube- lectronic +asics V- (ransistor 8+?(9 as a switch

•

7sing bipolar transistors as switches

Power inputs Powering devices is i$portant and there are $any for$ factors for supplying input # co$$on one is the 1 $$ barrel type that can $ate with input power plugs (hese typically output 2D or higher which are, of course, fatal to a HIP

Page 291

 #n e4cellent power source for use when working with breadboards is the very cheap M+10 (hese can be found for under a dollar on e+ay (hey take input fro$ either 7+ or barrel plug power sources and deliver either 3D or 2D which is configurable through 6u$pers (he M+10 is e4tre$ely breadboard friendly (he barrel input should be between @2D and 1D (he $a4i$u$ output current is =00$#

If we have a voltage input higher than we can use we need to use a voltage regulator device to bring it down to the desired value #n e4cellent e4a$ple of this is the :M31= een fro$ the front, the pins fro$ left to right are #d6ust, utput and Input (he :M31= has an input up to C0D with a regulated output between 12D and =D with a $a4i$u$ current load of # (he :M31= produces a constant voltage output as long as the input voltage is greater than the desired output voltage

(he e/uation for the output voltage is given by R 2 V OUT =1.25 V ( 1 + )  R 1

Page 292

For e4a$ple, if we want an output of 2D then we have 2D Q 12D81K".C09 (his gives " as =0  #n alternate solution for providing power to HIP is to use a *buck step down converter* (hese can take inputs of fro$ @D to BD and step down to 2D (here is an I called the MP12BC for which there are $odules available at about the ;3 price range

ee also•

(he power syste$

•

+readboard power supply M+10 review

•

:M31= Eata heet

•

:earning about lectronics L :M31= Doltage "egulator 

•

MP12BC Eatasheet

Current and Voltage meters (he ability to display the voltage and current consu$ption within a solution can be useful (his can be used to predict battery duration and deter$ine if we are approaching any boundaries of tolerance (here is a co$$on :E $eter available for a few dollars that shows both current and voltage heck 'ery carefully you are buying the correct ones (here are so$e $odels that re/uire an e4ternal shunt 7nless you are working with high voltages 8eg 20K D9 then you don't want this kind

!hen these devices arrive, there is no docu$entation with the$ which is a sha$e onnected to the $eter are two sets of wires ne s$all set with two connections which are red and black (hese are the power input to drive the $eter (his is a source fro$ C2D L Page 29/

30D (he larger set of leads has three taps (hese are red, black and blue (he wiring of these should be as follows-

•

red  L

Doltage sense onnect this to where you wish to $easure the voltage between that wiring point and ground

•

  black L

•

  blue L

Around #lways connect this to ground

urrent sense onnect this to what would otherwise be ground on your circuit and pass the current through this wire

.eb programming (here is a school of thought that says the browser will beco$e the universal desktop for all applications Instead of applications having to drive the screen locally using a variety of different 7I technologies such as J)!indows, ?avaFJ, wing, !indows 7I and all the $any, $any others, applications will instead serve up H(M: that runs within the browser #ny data need by the 7I will be re/uested by the browser fro$ the app using "( #ny actions that need to be perfor$ed such as data base updates will again be perfor$ed by the #pp on re/uest of the user through the browser ot only will the browser beco$e the 7I but it opens up the opportunity for re$ote interaction with the application where today a thick 7I can only be used locally  #nother i$portant consideration is the variety of devices that can host a browser ot only does this include Ps but of course includes phones and tablets

Browser security (o allow geolocation fro$ files loaded fro$ the file syste$, we need to start hro$e with the e4tra flags *--allo%-file-access-from-files* $ google-crome --allo%-file-access-from-files

(o allow yourself to $ake cross site calls unsecured, start with * --disable-%ebsecurit,* $ google-crome -disable-%eb-securit,

Page 29

"4%T re8uests In the field of co$puters, the $o$ent that there was $ore than one in the world, we had the notion that they could collaborate to get work done #s networked devices have beco$e the nor$, various protocols and techni/ues have been designed to allow applications to work with each other (hese distributed co$puting technologies have been widely varied and include such $e$bers as ockets, E "P, !eb ervices 8#P.H((P9, ?M and $ore Here we look at a specific techni/ue called *"(* "( is the usage of the H((P protocol to trans$it infor$ation fro$ a caller to be processed by a server #s such, it is client.server oriented (he client for$ulates a "( re/uest by building and sending an H((P protocol re/uest over a (P.IP network (his re/uest is co$$only received by a server application that is listening at a well known port n receipt of the re/uest, the server analy%es the inco$ing data and perfor$s so$e corresponding task using the data supplied If needed, the server can then send back a response $essage to the original caller "( calls are stateless !hen a call is $ade fro$ the client to the server and the call co$pletes, there is no conte4t $aintained about that previous call

5O2 processing in ) !hen working with "(, we will invariably also be working with ? data #  library is available on github called 6son)c (he package can be installed on a HI using *libIso&c-de/* $ sudo apt-get libIso&-c-de/

(o use this library, we $ust include Iso&-cIso&5J and link with * -l Iso&-c* !e create a new instance of a struct Iso&7obIect using Iso&7obIect7&e%7obIect. Fro$ there, we can start populating it !e have pri$itives for creating the core typesype

unction

string

Dson>obDect>ne">string

integer

Dson>obDect>ne">int

 boolean

Dson>obDect>ne">boolean

loating

Dson>obDect>ne">double

obDect

Dson>obDect>ne">obDect

array

Dson>obDect>ne">array

!e can add pri$itives to an e4isting ob6ect usingIso&7obIect7obIect7add.existi&gDbIect "&ameJ" cildY

or we can add to an array withPage 29$

Iso&7obIect7arra,7add.existi&g+rra,DbIect cildY

(he ob6ects can be released by calling Iso&7obIect7put.obIect which decreases the reference count to the ob6ect and deletes it if it reaches %ero (o turn a ? ob6ect into a string, we use Iso&7obIect7to7Iso&7stri&g. (he storage returned is freed when the ? ob6ect that the string represents is released M so take care about that (o convert a ? string into a 6son ob6ect, we can use the Iso&7toke&er7parse. function (o get a para$eter of an ob6ect use Iso&7obIect7obIect7get7ex. ee also•

AitHub- 6son)c.6son)c

•

Eocu$entation

•

 6son)c . lib6son (utorial with 4a$ples

.sing postman for testing (here are a wide variety of tools available to test and debug "( based services My favorite is called * postma&* (his is a Aoogle hro$e based application that allows one to enter "( re/uests of all types with all kinds of para$eters (hese can be saved for later re)use nce the data has been entered, post$an can send the "( re/uest and show you the response

ee also•

Post$an ho$e page

riting a E& re0uest using ) For  progra$$ing, the "( interface library I reco$$end is called libcurl (his can be read about in $ore detail at the c7": section of the book

riting a E& re0uest using 2ode34s +aked into the ode6s supplied libraries are packages called * ttp* and *ttps* (he first $akes un)encrypted H((P calls while the second $akes : encrypted H((P calls +y using the reUuest. $ethod of classes we can $ake "( calls

(he general synta4 of the co$$and isttp5reUuest.optio&s ScallbackT

(he options para$eter is a structure which contains the details of the re/uest to be $ade (he callback para$eter is a ?avacript function that will be invoked when a response is returned

Page 29)

(he full details of the function can be found in the docu$entation so need to repeat the$ here :et us look at a sa$ple scenario I$agine there is a web service at ttpsexample5com that when passed a re/uest to sales with an accessNe, /uery para$eter returns a sales record in ? For e4a$plettpsexample5comsales`accessNe,91234

the response would be "u&its)old" 100 "re/e&ueEar&ed" 4!H56G 

(o achieve this in ode6s, we would use logic si$ilar to the following/ar ttp 9 reUuite.WttpWY ttp5reUuest. ost "example5com" pat "sales`accessNe,91234" metod "5parse.dataY re/e&ueEar&ed 9 parse?ata5re/e&ueEar&edY  _ process ere Y Y

ee also•

ode6s L httpre/uest89 #PI

riting an (pp that listens for E& re0uests  # full)blown !eb erver can listen for !eb re/uests and service the$ but the core notion of a "( service provider is that it is usually an application that is passively waiting for client re/uests For HIP, this would $ean that we want to listen for inco$ing re/uests and, when one arrives, process it (here are solutions for this pu%%le for $ost of the languages that we $ay wish to want to choose

-istening for 4E#% requests using Node.s

ode6s has a pre)supplied !eb erver class (his $akes it trivial to start listening for inco$ing client re/uests Here is an e4a$ple of use-

Page 29,

/ar ttp 9 reUuire.WttpWY co&st PD(*9G0G0Y fu&ctio& a&dle(eUuest.reUuest respo&se respo&se5e&d.W:lie&t reUuest arri/ed W ] reUuest5urlY  /ar ser/er 9 ttp5create)er/er.a&dle(eUuestY ser/er5liste&.PD(* fu&ctio&. co&sole5log.")er/er liste&i&g o& ttplocalosts" PD(*Y Y

For an H((P A( re/uest, it $ay carry /uery para$eters of the for$&ameJ9/alueJ&ameJ9/alueJ555

!e can parse these out using the ode6s class called * url* For e4a$ple/ar params 9 reUuire.WurlW5parse.reUuest5url trueY

In addition, fro$ the parsed 7":, we can also find the pat&ame property which, in "(, is e/uivalent to the na$e of the service being re/uested ee also•

+uild your first H((P server in ode6s

•

ode6s L H((P class

•

ode6s L 7": class

.eb%ocket !ebocket is both an #PI and a protocol introduced in H(M:2 i$ply put, if we i$agine an H((P server sitting waiting for inco$ing H((P re/uests, we can convert a current re/uest into a socket connection between the server and the browser such that either end can send data to be received by its partner Here we see a raw re/uest to upgrade an H((P connection to a !ebocket connection
ee also•

ht$l2rocks L Introducing !ebockets- +ringing ockets to the !eb

•

(he !ebocket protocol L "F@C22

•

(he !ebocket #PI

•

websocketorg

•

!ikipedia L !ebocket

( e!ocket !rowser hosted application (he highest likelihood is that you will be running your Pi as a !ebocket server (his would i$ply that you are going to have browser hosted applications that will be connecting to a !ebocket server as clients and fro$ there, you will likely be writing so$e !ebocket client code & if nothing else then for unit testing your server +ecause of that, we will now spend so$e ti$e talking about what is involved in writing a !ebocket client application

:et us assu$e that we will be writing ?avacript hosted in the browser !e start by creating an instance of a !ebocket ob6ect passing in the 7": to the !ebocket server/ar %s 9 &e% 'eb)ocket."%ssomeostJSsomeportJT"Y

ote the 7": prefi4 value of * %s* to indicate that a !ebocket is being re/uested If one needs additional security, the prefi4 can be changed to *%ss* to specify that we wish to use : encryption (he !ebocket #PI is $ostly event driven and there are a nu$ber event types of interest to us-

•

ope& L Invoked when the connection to the !ebocket server has been established and we are now ready to send or receive data !e can define this with the *o&ope&* property of the !ebocket as a function reference

•

message L "eceive a $essage fro$ the server !e can define this with the *o&message* property of the !ebocket as a function reference (he callback function is invoked asynchronously when a new $essage is sent by the browser (he event $essage passed as a para$eter to the callback contains-

◦ data L (he data received over the connection For e4a$ple%s5o&message 9 fu&ctio&.messageE/e&t  co&sole5log."?ata " ] messageE/e&t5dataY Y

•

error L "eceive an indication that an error was detected !e can define this with the *o&error* property of the !ebocket as a function reference

•

close L "eceive an indication that a re/uest to close the connection was detected

Page 299

!e can define this with the * o&close* property of the !ebocket as a function reference vent handlers can be registered either with an * o&e/e&tJ* $echanis$ or with an addE/e&tAiste&er. call For e4a$ple, to register to receive a callback when the connection to the socket server has been co$pleted, we would code%s5o&ope& 9 fu&ctio&.   ?o someti&g 555 Y

(ake care to note the lower case on the event na$e (he property is *o&ope&* and not *o&Dpe&* (here are two $ethods defined on a !eb ocket ob6ect (hose are-

•

se&d L end data to a !eb ocket server !hen called, the browser application will receive a new $essage over the socket (he signature of the function is-

se&d.data

(ypically what we send is a tring If we wish to send an ob6ect, we would convert it to ? first

•

close L lose the connection to a !eb ocket server (he close. $ethod takes two para$eters-

◦ close code L #n integer close code describing the reason for the close ▪ 1000 L :T"M#: ▪ 1001 L :TAIAT#!#N ◦ status $essage L # string describing the close reason Finally, there are a few attributes-

•

read,)tate L (he state of the !ebocket connection Dalues include◦ !ebocket(IA ◦ !ebocketP L (he connection to the server is open ◦ !ebocket:IA ◦ !ebocket:E

•

buffered+mou&t L #$ount of data that is buffered pending trans$ission to the !ebocket server

•

protocol L (he !ebocket server selected protocol being used

)*+P as a e!ocket server !hen we start to think of the HIP as processing !ebocket re/uests, we now have options available to us !hen the browser re/uests that a !ebocket re/uest is $ade to HIP, there Page /00

will be a server side 8HIP9 application that owns the server side half of the socket connection (hat application is one that you will be writing #s such, the nature of that application should be under your control and, of course, the core nature of the application is the language in which it is written #s we have seen, we have a rich assort$ent of languages available to us and now we need to look at the different technologies we could use to leverage a !ebocket fro$ that language

Web#oc+et #er"er for C using libwebsoc+et

(o build lib%ebsocket, we $ust install the pre)re/ packages called cmake and libsslde/ #fter that, one need only follow the instructions defined in the lib%ebsocket web site and the build co$pletes cleanly on a HIP environ$ent #lternatively, one can 6ust install the pre)co$piled package called *lib%ebsockets-de/* $ sudo apt-get i&stall lib%ebsockets-de/

(o write an app, we have to include the header file lib%ebsockets5J !e $ust also link with lib%ebsockets (he high level nature of writing a libwebsocket app is as follows-

•

etup the environ$ent

•

+uild a conte4t

•

:oop around a call to lib%ebsocket7ser/ice. to service re/uests

(he creation of a conte4t is through the use of lib%ebsocket7create7co&text. (he return fro$ this is a struct lib%ebsocket7co&text pointer If we end up no longer needing the conte4t, we should release it "ith a call to lib%ebsocket7co&text7destor,.. (he input to lib%ebsocket7create7co&text is a pointer to a struct l%s7co&text7creatio&7i&fo (his structure has to be populated before it can be used pecifically-

•

port L the port nu$ber on which to listen

•

protocols L an array of struct lib%ebsocket7protocols

•

gid, uid L ecurity info, should likely be )1 for our purposes

 #n e4a$ple initiali%ation $ight bestruct l%s7co&text7creatio&7i&fo i&foY memset.i&fo 0 siCeof.i&foY i&fo5port 9 port &umberJY i&fo5gid 9 -1Y i&fo5uid 9 -1Y i&fo5protocols 9 protocolsY

(he protocols array defines the protocols that the server will handle (he for$at of this struct is-

• Page /01

&ame L (he na$e of the protocol

•

callback L # callback function

•

perTsessionTdataTsi%e

•

r4TbufferTsi%e

•

owningTserver 

•

protocolTinde4

(he array $ust be ter$inated by a 7:: entry (he first entry in the array must be an H((P protocol handler # si$ple way to initiali%e the protocols isstruct lib%ebsocket7protocols protocolsST9   "ttp-o&l," ttp:allback 0   "dumb-i&creme&t-protocol" dumb=&creme&t:allback 0   >8AA >8AA 0  Y

(he signature of a callback handler isi&t callback.struct lib%ebsocket7co&text Rco&text struct lib%ebsocket R%si e&um lib%ebsocket7callback7reaso&s reaso& /oid Ruser /oid Ri& siCe7t le&

nce we have set up our environ$ent we need to repeatedly call lib%ebsocket7ser/ice. (his takes as input the conte4t and a ti$e to block 8in $secs9 between polls for work For e4a$plelib%ebsocket7ser/ice.co&text !0Y

(he $a6ority of the work is perfor$ed in the callback handlers (he library provides so$e assistance with so$e of the $ore funda$ental tasks

•

lib%ebsockets7ser/e7ttp7file L end the content of a na$ed file down the socket to the partner

!hen a callback function is invoked, we are supplied a reason code (here are $any possible reasons and what we do when we receive a callback is key o$e of the $ore co$$on reasons are-

•

A')7:+AAB+:N7E)*+BA=);E? L Handshake with the partner has now co$pleted

•

A')7:+AAB+:N7(E:E=E L Inco$ing data has arrived (he data is in the in buffer with the supplied length

•

A')7:+AAB+:N7P(D*D:DA7=>=* L alled once to allow initiali%ation to be perfor$ed 8if needed9

(o actually write data down a web socket, we e$ploy the lib%ebsocket7%rite. function Page /02

(he signature of the function isi&t lib%ebsocket7%rite. struct lib%ebsocket R%si u&sig&ed car Rbuf siCe7t le& e&um lib%ebsocket7%rite7protocol protocolY

(his is an overloaded function that can send data through H((P or through a !ebocket !hen sending through a !ebocket, the protocol type should be A')7'(=*E7B=>+(L or A')7'(=*E7*E@* (he length is the nu$ber of bytes to send (ake care with the buffer though !hen writing through a web socket, the buffer must be larger than e4pected pecifically, it $ust have A')7)E>?7B8E(7P(E7P+??=>< bytes in front of it and A')7)E>?7B8E(7PD)*7P+??=>< after it Here is a co$plete sa$ple server applicationFi&clude stri&g5J Fi&clude stdio5J Fi&clude stdlib5J Fi&clude lib%ebsockets5J static i&t se&d'eb)ocket?ata.struct lib%ebsocket R%si u&sig&ed car Rbuf siCe7t le&Y static struct lib%ebsocket Rg'siY static i&t ttp:allback.struct lib%ebsocket7co&text Rco&text struct lib%ebsocket R%si e&um lib%ebsocket7callback7reaso&s reaso& /oid Ruser /oid Ri& siCe7t le&  pri&tf."ttp:allbackK reaso&9x^&" reaso&Y i&t ret 9 0Y s%itc.reaso&  case A')7:+AAB+:N7E)*+BA=);E? pri&tf."A')7:+AAB+:N7E)*+BA=);E?^&"Y g'si 9 %siY se&d'eb)ocket?ata.%si ";elloK" HY breakY case A')7:+AAB+:N7P(D*D:DA7=>=* pri&tf."A')7:+AAB+:N7P(D*D:DA7=>=*^&"Y breakY case A')7:+AAB+:N7;**P pri&tf."A')7:+AAB+:N7;**P - pat is ^"s^"^&" .car Ri&Y lib%ebsockets7ser/e7ttp7file.co&text %si .car Ri& "textplai&"Y ret 9 1Y breakY case A')7:+AAB+:N7=A*E(7>E*'D(N7:D>>E:*=D> pri&tf."A')7:+AAB+:N7=A*E(7>E*'D(N7:D>>E:*=D>^&"Y breakY case A')7:+AAB+:N7=A*E(7P(D*D:DA7:D>>E:*=D> pri&tf."A')7:+AAB+:N7=A*E(7P(D*D:DA7:D>>E:*=D>^&"Y breakY case A')7:+AAB+:N7+??7PDAA7? pri&tf."A')7:+AAB+:N7+??7PDAA7?^&"Y breakY case A')7:+AAB+:N7?EA7PDAA7? pri&tf."A')7:+AAB+:N7?EA7PDAA7?^&"Y breakY  retur& retY  static i&t dumb=&creme&t:allback.struct lib%ebsocket7co&text Rco&text struct lib%ebsocket R%si e&um lib%ebsocket7callback7reaso&s reaso& /oid Ruser /oid Ri& siCe7t le&  pri&tf."?umbi&creme&tcallbackK reaso&9x^&" reaso&Y

Page /0/

s%itc.reaso&  case A')7:+AAB+:N7P(D*D:DA7=>=* pri&tf."A')7:+AAB+:N7P(D*D:DA7=>=*^&"Y breakY  retur& 0Y  static i&t se&d'eb)ocket?ata.struct lib%ebsocket R%si u&sig&ed car Rbuf siCe7t le&  u&sig&ed car RtmpBuf 9 malloc.A')7)E>?7B8E(7P(E7P+??=>< ] le& ] A')7)E>?7B8E(7PD)*7P+??=><Y memcp,.tmpBuf]A')7)E>?7B8E(7P(E7P+??=>< buf le&Y i&t rc 9 lib%ebsocket7%rite.%si tmpBuf]A')7)E>?7B8E(7P(E7P+??=>< le& A')7'(=*E7*E@*Y free.tmpBufY retur& rcY  /oid i&it'eb)ockets.  struct lib%ebsocket7protocols protocolsS3TY memset.protocols 0 siCeof.protocolsY protocolsS0T5&ame 9 "ttp-o&l,"Y protocolsS0T5callback 9 ttp:allbackY protocolsS1T5&ame 9 "dumb-i&creme&t-protocol"Y protocolsS1T5callback 9 dumb=&creme&t:allbackY struct l%s7co&text7creatio&7i&fo i&foY memset.i&fo 0 siCeof.i&foY i&fo5port 9 3000Y i&fo5gid 9 -1Y i&fo5uid 9 -1Y i&fo5protocols 9 protocolsY struct lib%ebsocket7co&text Rco&textY co&text 9 lib%ebsocket7create7co&text.i&foY if .co&text 99 >8AA  pri&tf."ailed to create co&textK"Y  %ile.1  lib%ebsocket7ser/ice.co&text !0Y  

ee also •

libwebsocketsorg

•

:ibwebsockets Introduction

•

(est drive libwebsockets library L a si$ple server 

Web#oc+et #er"er for C using no'oll

(he library called *noPoll* is an open source i$ple$entation of !ebocket for  It has been found to co$pile cleanly for the HIP on "aspbian #fter co$pilation and installation, the headers can be found in usrlocali&clude&opoll and the linkable libraries in usrlocallib (o use noPoll in your app, you $ust include * &opoll5* (he conte4t is very i$portant and should be created at the start and disposed of at the end For e4a$ple&oPoll:tx Rctx 9 &opoll7ctx7&e%.Y  ?o someti&g M &opoll7ctx7u&ref.Y

nce a conte4t has been created, we can then register ourselves as a serverPage /0

&oPoll:o& Rliste&er 9 &opoll7liste&er7&e%.ctx "0505050" "1234"Y &opoll7ctx7set7o&7msg.ctx liste&er7o&7message7a&dler >8AAY &opoll7loop7%ait.ctx 0Y

!hen a $essage is received, the registered function 8listenerTonT$essageThandler9 will be invoked/oid liste&er7o&7message7a&dler.   &oPoll:tx Rctx &oPoll:o&& Rco&&   &oPollsg Rmsg &oPollPtr user?ata   ?o someti&g &opoll7co&&7se&d7text.co&& "*a&ks" !Y 

ee also•

noPoll ho$e page

•

noPoll core library $anual

•

noPoll $odules

Web#oc+et #er"er in !a"a#cript

(he np$ package called %s can be used to provide !eb ocket support #t a high level, the function is/ar ser/er 9 reUuire.WttpW5create)er/er.Y /ar 'eb)ocket)er/er 9 reUuire.W%sW5)er/erY /ar %ss 9 &e% 'eb)ocket)er/er.ser/er ser/erY ser/er5liste&.portJY

!e can now receive !eb ocket re/uests First there is the%ss5o&.Wco&&ectio&W fu&ctio&.%s   :ode ere 555 Y

(his will register a connection handler that will be invoked when a client connects to the server (he %s para$eter passed in on the connection event is an instance of a !eb ocket connection 7pon this we can receive $essages with%s5o&.Wmessage fu&ctio&.message   :ode ere 555 Y

 #nd we can also send data through this connection with%s5se&d.dataY

:ater on we will also see that the popular !eberver package called *e4press* is also able to serve as a !ebocket provider ee also• Page /0$

socketio

•

np$ L ws

•

4press !ebocket support

,ode2Es as a .eb %er'er  ode6s can $ake a pretty useful !eb erver

2ode34s and E>press !hile ode6s has a built in package for H((P serving, it is reco$$ended to spend a little ti$e learning *express* Here is a sa$ple script that will serve files fro$ the local directory/ar express 9 reUuire."express"Y /ar app 9 express.Y app5use.express5static."5"Y app5liste&.3000 fu&ctio&.  co&sole5log."Express app started o& port 3000"Y Y

4press has a nu$ber of concepts associated with it 5ey a$ongst these are the notions of-

•

middle%are L # set of handlers that get e4ecuted in a chain when a re/uest arrives (he handler can read and write both the re/uest and response Middleware is set up using the app5use. #PI

•

routi&g L Functions e4ecuted conditional on the path of the original re/uest "outing is set u! using the app5get.4 app5post. ?etc@ %PI.

ee also•

ode6s L 4press

•

+uild your first H((P erver in ode6s

E5press middleware

4press provides so$e pre)built $iddleware co$ponents that are especially useful-

•

express5static L erve static web pages

E5press routing

!e add a route using the #PI of the for$ app5get."patJ" fu&ctio&.reUuest respo&se Y

(he routing also handles other $ethods beyond A( (he path synta4 for the routing can be constant as in * ello* M which will $atch e4actly the path *ello* or it can contain $eta instructions such as * ellopla&et* where the Page /0)

function will be e4ecuted if the path starts with * ello* and the re$ainder of the path will be available as a property called reUuest5params5pla&et For e4a$ple, browser re/uests tottpostJello%orld ttpostJelloEart

will both resolve to the sa$e function with different para$eters values for reUuest5params5pla&et (he re/uest and response para$eters are rich with capabilities Fro$ these we can set and get input and output values Here are so$e e4a$ples-

•

reUuest5Uuer, L an ob6ect that has properties for each of the /uery para$eters

•

respo&se5e&d. L # function to co$plete the response for the re/uest

•

respo&se5status.codeJ L et the status code for the response

ee also•

4press L re/uest

•

4press L response

E5press Web#oc+et support

4press can support the !eb ocket protocol with the help of an additional $odule called *express-%s*  #t a high level, we add support as follows/ar express 9 reUuire."express"Y /ar app 9 express.Y /ar express's 9 reUuire."express-%s".appY

ow the environ$ent has additional !eb ocket support (o receive a $essage we can useapp5%s."patJ" fu&ctio&.%s reU  %s5o&.WmessageW fu&ctio&.msg   ;a&dle te message ere  Y

(o send a $essage we can use %s5se&d.data  #n alternative to using *express-%s* is to use the popular package called * %s* ee also•

!ebocket

•

np$ L e4press)ws

•

np$ L ws

Page /0,

E5press as an https ser"er

(o run e4press as https server, we need credentials (hese can be created withope&ssl reU -&e% -x!0# -&e%ke, rsa204G -ke,out ke,5pem -out cert5pem -da,s 3H! -subI ":>9kolba&" -&odes

(his will generate a keype$ and a certpe$ file

 E3uery – 1a'a%cript framework (he 6Uuery ?avacript fra$ework provides a lot of the service to ?avacript in the browser that aren't otherwise available Many of these relate to EM progra$$ing which is the technology used to change how the browser displayed web page is shown However there are other features of 6Uuery that have non)7I applicability ttps5create)er/er. ke, fs5readile),&c."ke,5pem" cert fs5readile),&c."cert5pem"  app5liste&.3001Y

.sing 4/uery (he si$plest way to use 6Uuery is to include it within the eadJ of your page For e4a$plescript src9"ttpsaIax5googleapis5comaIaxlibsIUuer,25154IUuer,5mi&5Is"JscriptJ

Nou can bring it in fro$ a variety of E locations or serve a copy of it up fro$ your local !ebserver If we load *6/uery* through *bower*, we should usescript src9"5bo%er7compo&e&tsIUuer,distIUuer,5Is"JscriptJ

#aking E& re0uests using 4/uery Fro$ with any ?avacript application, sooner or later we will be $aking "( calls (he function called *IMuer,5aIax.* $akes the "( call for us It takes a para$eter which is the settings for the re/uest which is a ?avacript ob6ect (hat ob6ect controls how the re/uest shall be $ade

•

url L (he target of the re/uest

•

data L #n ob6ect to be passed as na$e.value pairs for the /uery string If the $ethod is P( then this is the data sent in the body of the $essage

•

co&te&t*,pe L (he Mi$e :o&te&t-*,pe H((P header value

•

success L # ?avacript function that is called when a successful return occurs fro$ the "( re/uest (he function has the signature of-

◦ +&,ti&g L data ◦ )tri&g L te4ttatus Page /0<

◦ IU@;( L 6/JH" •

error  a ?avacript function that is called when an error return occurs (he funcation has the signature of-

◦  6/JH" ◦ te4ttatus ◦ error(hrown •

co&text L (he ?avacript ob6ect 8co$$only passed as this9 that will be the conte4t used for the callback functions

•

metod L (he type of H((P co$$and o$$only either *
•

user&ame L # userna$e to be passed

•

pass%ord L # password to be passed

+ee alsoK •

 6Uuerya6a489

Using Bower  +ower is a package $anager for web based applications It has a pre)re/ of ode6s and can be installed through np$ +ower can be installed using$ sudo &pm i&stall bo%er -g

nce installed, we can ask bower to install packages for us For e4a$ple, to install 6/uery, we would run$ bo%er i&stall IUuer,

(his would then create a new directory called *bowerTco$ponents* and underneath that, download and install *6/uery* o$e of the $ore co$$on packages we $ay use include-

•  6/uery •

three6s

ee also•

+ower ho$e page

•

+ower packages

"obotics "obotics is our desire to control $ove$ent fro$ our HIP (his is likely to be $otors but Page /09

could be servos or boat propellers

Heading in a direction :et us consider the notion that we wish our robot to head off in a direction :et us assu$e we have control over speed and the ability to turn left or right #s an analogy, i$agine sitting in the drivers seat of your car Nou have a co$pass on a gi$bal on your dashboard and hence you can tell what direction you are facing ow i$agine that instead of being on a road which contrains the directions you can driver you are instead on a flat car park that is 8for our purposes9 infinite in all directions :et us now consider what has to be done to drive in a particular direction I$agine our goal is to drive in the direction *(* 8for target9 where *(* is a co$pass direction e4presses as an angle in degrees with 0 being orth, <0 being ast, 1B0 being outh and =0 being !est #t any given point we can ask ourselves *which direction are we currently facing* :et us call that direction ** 8for current9 !hich way should we turn the steering wheel to get us going in the right direction (he answer is to turn it in the direction which has the shortest angle between ** and *(* For e4a$ple if *(* is <0 and ** is 10 then by turning the wheel right we would rotate through B0  to reach our ob6etive If we turned the wheel left we would rotate through B0  (he generic answer is that we have two values"ight turn Q  ( L   :eft turn Q   L (  !e calculate both and choose the turn direction which results is the s$aller of the two #s we turn, we should be recalculating our deviation fro$ desired to direction fro$ actual direction and continue to turn while the deviation is greater than so$e threshold ur specific pro6ect will deter$ine what that threshold is (he chances are high that we should not e4pect to hit the target e4actly as there can be a $yriad of factors affecting the deter$ination !e $ay also have to account for other real)world factors such as inertia If we are turning and e4actly hit our desired target, it $ay take so$e 8hopefully s$all9 anount of ti$e to *stop turning* Euring that interval, we $ay find that we have now over turned and have to turn back in the opposite direction which again $ay cause us to over)steer # solution $ight be to change our  rate of turn as a function of how far fro$ our target direction we are If we are 6ust a s$all angle off, then steer a proportionally s$all angle of turn to co$e back on course In the real world, there $ay be other forces acting on our robot such as wind, slopes, waster current or errors in $otor control +y incorporating a feedback loop, we can keep ad6usting our steering to keep us on track If we wanted to beco$e even $ore sophisticated, we could $easure our turns rate as a function of our current heading and $odel predictions of effects of different turns o far we have assu$ed that we can control the turn a$ount but we have a second consideration which is the speed of propulsion If you sit in your stationery car, you can turn the wheel all day long and not change your heading nly when you apply the gas and start $oving in your *local forward* will you start to change direction (he ti$e taken to reach your desired target direction is now a function of both how $uch you turned the wheel and how Page /10

fast you are going

ProEects .iring6CHIP For the "aspberry Pi world, there is a fantastic package called *!iring)Pi* that provides a  language interface library to  progra$s to be able to perfor$ hardware interfacing #t the ti$e of writing 8?uly 01@9, there is not an obvious e/uivalent for HIP & so let us build one (he #PIs we need arei&t %iri&g:;=P)etup. /oid pi&ode.i&t pi& i&t mode /oid digital'rite.i&t pi& i&t /alue i&t digital(ead.i&t pi& i&t %iri&g:;=P=2:)etup.i&t bus i&t de/=dY i&t %iri&g:;=P=2:(ead.i&t fdY i&t %iri&g:;=P=2:(ead(egG.i&t fd i&t regY i&t %iri&g:;=P=2:(ead(eg1H.i&t fd i&t regY i&t %iri&g:;=P=2:'rite.i&t fd i&t dataY i&t %iri&g:;=P=2:'rite(egG.i&t fd i&t reg i&t dataY i&t %iri&g:;=P=2:'rite(eg1H.i&t fd i&t reg i&t dataY

 # AitHub pro6ect has been created for this task and can be found herehttps-..githubco$.nkolban.wiring)HIP

Visuali7ing *PU=A= orientation In this pro6ect we want to visuali%e the orientation of an MP7@020 in 3E !e will use (hree6s to achieve that goal (he browser will have a !eb ocket re/uest opened to a ode6s app running on HIP HIP will obtain MP7@020 data is then sent to the browser for visuli%ation

Building libsoc Install git, autoconf, libtool, auto$ake, pkg)config, libpython=)dev $ sudo apt-get i&stall git autoco&f libtool automake pkg-co&fig libp,to&256-de/

lone libsoc $ git clo&e ttpsgitub5comIackmitclibsoc5git libsoc5git

hange into the libsocgit directory $ cd libsoc5git

"un autoreconf )i $ autoreco&f -i

Page /11

(his will take a bit and build an environ$ent "un .configure $ 5co&figure

ow we build the library $ make

 #nd finally we install it$ sudo make i&stall

If when you co$pile a progra$ that uses libsoc and run it and you get an error that readserror %ile loadi&g sared libraries libsoc5so52 ca&&ot ope& sared obIect file >o suc file or director,

(hen that $eans that the installation directory for libsoc libraries is not in your shared library lookup path et or change the A?7A=B(+(L7P+*; environ$ent variable to include that directory which is co$$only .usr.local.lib ee also•

libsoc ho$e page

"ecommended packages •

gea&, L a A7I based te4t editor 

•

build-esse&tial L  co$pilation tools

•

&fs-commo& L F tools to be able to access re$ote file syste$s

•

pcma&fm L File $anager 

How CHIP boots !e know that HIP runs :inu4, but how does HIP actually load :inu4 in the first place (he act of loading an operating syste$ is called *booting* fro$ the phrase *bootstrap* and follows the story of one pulling one self up by one's bootstraps (he HIP is hard)coded to load a progra$ called *uboot* which is an instance of a boot loader application (hrough uboot, HIP has enough power to load the :inu4 kernel and get things started +y default, when uboot runs, it auto$atically loads the :inu4 kernel however this can be interrupted by pressing a key during a start)up pause period of two seconds at start)up Fro$ there, one will be dropped into the uboot shell in which one can perfor$ co$$ands "unning *help* at this pro$pt produces the list of sub)co$$ands that can be e4ecuted Here is a current listPage /12

` base bdi&fo bmp boot bootd bootelf bootm bootp boot/x bootC cpart clrlogo cmp co&i&fo cp crc32 dfu dcp dm eco edite&/ e&/ erase exit ext2loadext2ls ext4loadext4ls ext4siCefalse fastbootfati&fo fatload fatls fatsiCe fat%ritefdt fli&fo fst,pe go gpio elp i2c imi&fo imxtractitest load loadb loads loadx load, loop ls md mii mm mtdpartsm% &a&d Page /1/

alias for WelpW pri&t or set address offset pri&t Board =&fo structure ma&ipulate BP image data boot default i5e5 ru& WbootcmdW boot default i5e5 ru& WbootcmdW Boot from a& EA image i& memor, boot applicatio& image from memor, boot image /ia &et%ork usi&g BDD*P**P protocol Boot /x'orks from a& EA image boot Ai&ux C=mage image from memor, ca&ge acti/e partitio& fill te boot logo area %it black memor, compare pri&t co&sole de/ices a&d i&formatio& memor, cop, cecksum calculatio& ?e/ice irm%are 8pgrade boot image /ia &et%ork usi&g ?;:P**P protocol ?ri/er model lo% le/el access eco args to co&sole edit e&/iro&me&t /ariable e&/iro&me&t a&dli&g comma&ds erase A+); memor, exit script load bi&ar, file from a Ext2 files,stem list files i& a director, .default  load bi&ar, file from a Ext4 files,stem list files i& a director, .default  determi&e a fileWs siCe do &oti&g u&successfull, use 8)B astboot protocol pri&t i&formatio& about files,stem load bi&ar, file from a dos files,stem list files i& a director, .default  determi&e a fileWs siCe %rite file i&to a dos files,stem flatte&ed de/ice tree utilit, comma&ds pri&t A+); memor, i&formatio& Aook up a files,stem t,pe start applicatio& at address WaddrW Uuer, a&d co&trol gpio pi&s pri&t comma&d descriptio&usage =2: sub-s,stem pri&t eader i&formatio& for applicatio& image extract a part of a multi-image retur& truefalse o& i&teger compare load bi&ar, file from a files,stem load bi&ar, file o/er serial li&e .kermit mode load )-(ecord file o/er serial li&e load bi&ar, file o/er serial li&e .xmodem mode load bi&ar, file o/er serial li&e .,modem mode i&fi&ite loop o& address ra&ge list files i& a director, .default  memor, displa, == utilit, comma&ds memor, modif, .auto-i&creme&ti&g address defi&e flas&a&d partitio&s memor, %rite .fill >+>? sub-s,stem

&boot - boot from >+>? de/ice &fs - boot image /ia &et%ork usi&g >) protocol &m - memor, modif, .co&sta&t address part - disk partitio& related comma&ds pi&g - se&d =:P E:;D7(EM8E)* to &et%ork ost pri&te&/- pri&t e&/iro&me&t /ariables protect - e&able or disable A+); %rite protectio& pxe - comma&ds to get a&d boot from pxe files reset - Perform (E)E* of te :P8 ru& - ru& comma&ds i& a& e&/iro&me&t /ariable sa/e - sa/e file to a files,stem sa/ee&/ - sa/e e&/iro&me&t /ariables to persiste&t storage sete&/ - set e&/iro&me&t /ariables setexpr - set e&/iro&me&t /ariable as te result of e/al expressio& so%/ar - pri&t local ussell /ariables siCe - determi&e a fileWs siCe sleep - dela, executio& for some time source - ru& script from memor, s,sboot - comma&d to get a&d boot from s,sli&ux files test - mi&imal test like bi&s tftpboot- boot image /ia &et%ork usi&g **P protocol true - do &oti&g successfull, ubi - ubi comma&ds ubifsload- load file from a& 8B=) files,stem ubifsls - list files i& a director, ubifsmou&t- mou&t 8B=) /olume ubifsumou&t- u&mou&t 8B=) /olume ums - 8se te 8) S8)B ass )torageT usb - 8)B sub-s,stem usbboot - boot from 8)B de/ice /ersio& - pri&t mo&itor compiler a&d li&ker /ersio&

ne of the $ore interesting co$$ands is * pri&te&/* which lists the environ$ent variables in effect It is these variables which control so$e of how the kernel is startedbaudrate911!200 boot7a7script9load $de/t,pe $de/&um$bootpart $scriptaddr $prefix$scriptY source $scriptaddr boot7extli&ux9s,sboot $de/t,pe $de/&um$bootpart a&, $scriptaddr $ prefixextli&uxextli&ux5co&f boot7prefixes9 boot boot7script7dcp9boot5scr5uimg boot7scripts9boot5scr5uimg boot5scr boot7targets9fel usb0 pxe dcp bootargs9root9ubi0rootfs rootfst,pe9ubifs r% earl,pri&tk ubi5mtd94 bootcmd9gpio set PB2Y if test -& $fel7booted  test -& $scriptaddrY te& eco .EA bootY source $scriptaddrY fiY mtdpartsY ubi part 8B=Y ubifsmou&t ubi0rootfsY ubifsload $fdt7addr7r bootsu&!i-rG-cip5dtbY ubifsload $ker&el7addr7r bootC=mageY sete&/ bootargs $bootargs $ker&elarg7/ideoY bootC $ker&el7addr7r - $fdt7addr7r bootcmd7dcp9usb startY if dcp $scriptaddr $boot7script7dcpY te& source $ scriptaddrY fi bootcmd7fel9if test -& $fel7booted  test -& $scriptaddrY te& eco W.EA bootWY source $scriptaddrY fi bootcmd7pxe9usb startY dcpY if pxe getY te& pxe bootY fi bootcmd7usb09sete&/ de/&um 0Y ru& usb7boot bootdela,92 bootm7siCe90xa000000 dip7addr7r90x43400000 dip7o/erla,7cmd9if test -& "$dip7o/erla,7&ame"Y te& ubifsload $dip7addr7r $dip7o/erla,7dir$dip7o/erla,7&ameY fi Page /1

dip7o/erla,7dir9libfirm%are&extti&gcocipearl, distro7bootcmd9for target i& $boot7targetsY do ru& bootcmd7$targetY do&e etact9usb7eter etaddr902ce044262#6 fdt7addr7r90x43000000 fdtco&troladdr9!ab2H!20 fdtfile9su&!i-rG-cip5dtb ker&el7addr7r90x42000000 mtdids9&a&d09su&xi-&a&d50 mtdparts9mtdparts9su&xi-&a&d504m.spl4m.spl-backup4m.uboot4m.e&/-.8B= preboot9usb start pxefile7addr7r90x43200000 ramdisk7addr7r90x43300000 sca&7de/7for7boot9eco )ca&&i&g $de/t,pe $de/&um$bootpart555Y for prefix i& $ boot7prefixesY do ru& sca&7de/7for7extli&uxY ru& sca&7de/7for7scriptsY do&e sca&7de/7for7boot7part9part list $de/t,pe $de/&um -bootable de/plistY e&/ exists de/plist || sete&/ de/plist 1Y for bootpart i& $de/plistY do if fst,pe $de/t,pe $ de/&um$bootpart bootfst,peY te& ru& sca&7de/7for7bootY fiY do&e sca&7de/7for7extli&ux9if test -e $de/t,pe $de/&um$bootpart $ prefixextli&uxextli&ux5co&fY te& eco ou&d $prefixextli&uxextli&ux5co&fY ru& boot7extli&uxY eco ):(=P* +=AE? co&ti&ui&g555Y fi sca&7de/7for7scripts9for script i& $boot7scriptsY do if test -e $de/t,pe $de/&um$ bootpart $prefix$scriptY te& eco ou&d 8-Boot script $prefix$scriptY ru& boot7a7scriptY eco ):(=P* +=AE? co&ti&ui&g555Y fiY do&e scriptaddr90x43100000 serialF91H2!42ce044262#6 splaspos9mm stderr9serial stdi&9serialusbkbd stdout9serial usb7boot9usb startY if usb de/ $de/&umY te& sete&/ de/t,pe usbY ru& sca&7de/7for7boot7partY fi usb&et7de/addr9deadbeaf0001 /ideo-mode9su&xi620x4G0-24VH0mo&itor9composite-&tsco/ersca&7x940o/ersca&7,920

(o change the value of a variable, usesete&/ &ameJ /alueJ

to co$$it the changes, use sa/ee&/

 #t CC, the response fro$ version is8-Boot 201H501-gc233H4e .u& 01 201H - 0!!62! ]0000 +ll%i&&er *ec&olog, arm-li&ux-g&ueabif-gcc .8bu&tu !5251-22ubu&tu1 !5251 201!1010 <>8 ld .<>8 Bi&utils for 8bu&tu 252!51

Here are so$e of the $ore i$portant variables-

•

baudrate L (he baudrate to be used for serial output Eefault 11200

•

bootdela, L (he delay in seconds before the :inu4 kernel is loaded during which a user can interrupt the boot process Eefault is  seconds

•

stdout, stderr, stdi& L 7nknown

ee also-

• Page /1$

u)boot $anual

!nowledge %ources !hen learning anything new, it is always vital to know where to go to read and find out $ore For the HIP, there are so$e great places (he HIP ho$e page can be found herehttps-..ne4tthingco.pages.chip (he docu$entation for HIP can be found herehttp-..docsgetchipco$. (he ne4t is the HIP co$$unity foru$ found herehttps-..bbsne4tthingco. Fro$ here you will find an attractive foru$ where you can search previous U_# and post your  own /uestions 8and ideally eventually answer those sub$itted by others9  # co$$unity !iki can be found herehttp-..wwwchip)co$$unityorg.inde4php.MainTPage

Internet "elay Chat Internet "elay hat 8I"9 provides $ulti user chat roo$s covering every conceivable topic area ach topic is split into its own *roo$* or *channel* (here are $any tools one can use to access I" including popular ones such as He4hat However, if you want to 6ust tune in and see what is going on, you can access I" straight fro$ a browser pen the urlhttps-..webchatfreenodenet. Pick a nickna$e and enter the na$e of the channel you want to view-

•

Fcipsters L discussions on all things HIP

•

F&extti&gco L (he e4t(hingo chat roo$

"esearch reas •

!hat to have on a test board

◦ Header for alaea logic analy%er  Page /1)