1
2
3
3.1
3.2
4
4.1
4.1.1
4.1.2
4.2
4.2.1
4.2.2
4.2.3
5
5.1
5.1.1
5.1.2
5.1.3
5.2
5.2.1
5.2.2
5.3
5.3.1
5.3.2
6
7
7.1
7.2
7.3
7.4
7.5
7.6
TableofContentsAbstract
Acknowledgements
Context
NovemberFive
Goal&Requirements
Software
Environment
TheCaseforArchLinux
Dependencies
Controllingtheviewroom
Buildingblocks
Unifiedarchitecture
Optimizing&packaging
Hardware
Design&Prototyping
Microcontrollers
InfraredRemoteControl
UserI/O
Firmware
CloudAPI
Hardwarecontrols
Buildingtheendproduct
PCB
Casing
Conclusion&Summary
Appendices
ArchLinuxARMsetupandconfiguration
NeoPixelcurrentmeasurements
Eurocircuits
SMDsolderingprocess
CasingDesign
UserGuide
2
AbstractNovemberFive'sentertainmentroomisusedfordifferentpurposes–hostingpresentations,streamingkeynotes,takingabreakonthePlayStation,tonameafew–buttheexistingsetupwasannoyinglycomplex.Therewasaremoteoverload,andenoughdifferentsettingsandusecasesthattherewereafewhow-todiagramsattachedtothewall.Anembeddedsystemwasdesignedanddevelopedtosimplifycontrolofthisviewroom,whichcontainedthefollowingdevices:
OnkyoTX-NR809A/Vreceiverwith3differentzonesEpsonEH-TW5910projectorAppleTV-3rdgenerationTelenetAD2200DigicorderWeMoInsightswitch
Eachofthesedevicescommunicatedinitsownwayanduseditsownprotocol.SoftwarewaswrittentoencapsulatethesedifferentmethodsinasingleuniformAPIcapableofcontrollingalldevicesandkeepingtrackoftheconfigurationswherepossible.ThisAPIwasaccessiblethroughacommandlineinterface,hardwarecontrols,andaRESTAPI.
ThesoftwareranonaRaspberryPiZeromountedinsideaphysicalhandheldcontroller,whichwascustom-madeand3Dprinted.ThiscontrollerhousedacustomPCB,exposinganOLEDdisplay,8buttonswithRGBbacklighting,andavolumeknobwithbuilt-inpushbuttontoenabletheusertoquicklysetuptheentertainmentroom.
Foroptimaleaseofuse,presetscouldbedefinedthatconfiguredalldevicesaspleasedwithasinglebuttonpressorAPIcall.TheRESTAPIwasalsoconsumedbyNovemberFive'sSpencer-asmartall-in-onemobileworkplaceassistant-makingtheentertainmentroomcontrollablefromamobileapp.
Abstract
3
AcknowledgementsFirstoffI'dliketothankAP,thelecturersandmyfriendsforgivingmetheknowledgeandskillstogetwhereIamtoday,andinawaythatmademeenjoyeverysingleclass,labandproject.IdoubtthereisabetterschoolinBelgium.SpecialthankstoTimDams,MaartenLuyts,PatrickVanHoutvenandMarcSmetsfortheirinvolvementand(offersto)helpwiththisproject.
I'mverygratefultoNovemberFiveandallemployeesforofferingmethisinternshipandshowingmehowgreataworkplacecanbe.Ienjoyedeverysingledayatthecompany,everylunchmadebychefHilde,andeveryspampostonslack.SpecialthankstoNickVerbaendertandGeertWilleforcomingupwithafunandinterestingproject,andguidingmefrombeginningtoendinbringingittolife.Theytookthetimefordailystand-upmeetings,weeklydemos,andquestionsinbetween,helpingtoavoidproblemsearlyon,achieveabetterendresult,andlearnalot.BigthankstoNoémieSixforwritinganawesomeblogpostontheNovemberFivewebsite,andlettingmeborrowsomewordsforthisthesis.
IthankRichardStallman,LinusTorvaldsandallcontributorstotheGNUandLinuxprojectsforbuildingagreatandcompletelyfree/libre,opensourceoperatingsystem.IalsothankallcontributorsanddevelopersofFLOSSsoftwarethatrunsonthesesystems.IcouldwriteanotherthesisaboutmyloveforFLOSS,butI'llsaveusboththetrouble.ExtrathankstoJeroenDoggenandReinoutEyckermanforshowingmethispath.
LastlyI'dliketothankmyfamily,girlfriend,friends,andmycatNoodleforkeepingmemotivated,happy,andalive.
Antwerp,09/06/2016OliverHofkens
Acknowledgements
4
NovemberFiveThisprojectwasmadeaspartoftheinternshipofferedtomebyNovemberFive.NovemberFiveisaprivatelyownedtechnologycompanybasedinAntwerp.TheirmainbusinessismakinginnovativedigitalsolutionsforclientssuchasABInBev,Spotify,TheNewYorkTimesandCoca-Cola.Frommobiledevelopmenttotheweb,fromallformsofsoftwaretocustomhardware:theyembracethefullspectrumoftechnology.Formoreinformation,visitnovemberfive.co.
Goal&RequirementsTheNovemberFiveofficeshaveaspacecalledtheviewroom,whichfunctionsasbotharelaxingloungefortheemployeesaswellasaplacewherepresentationscanbegiven.Thisviewroomcontainsmanydifferentdevices,suchasaudiovisualequipmentandsmartlights,allcontrolledwiththeirownremotecontrolormobileapp.Thismadeithardandtimeconsumingtosetuptheroomforsomesimplescenarios,e.g.towatchtvwithsomeambientlightson,atleast3differentremotesand1mobileappwerenecessary.Thegoalofthisprojectwastomakethisprocessmuchsimplerandcontrolalldeviceswith1easytousecontrolpanel,capableofdefiningpresetswhichsetupeverythingaspleasedwithasinglebuttonpress.
Devicestocontrol
Thescopeoftheprojectincludedcontrolandstatetracking(wherepossible)ofthefollowingdevices:
OnkyoTX-NR809:Anaudio/videoreceiverthatconnectsallinputsourcesandoutputsinks,andcouldbeconsideredtheheartoftheviewroom.Ithas3zones:zone1isthevideoandaudiointheviewroomitself,zone2containsspeakersontheoutsideoftheviewroomwhichareusedforpresentationsorthefitnessarea,andzone3containsspeakersinthekitchen.Thisreceiverhasmorethan50configurableoptionsforzone1alone,fromsimpleinput/outputselectiontoadvancedaudiofine-tuning.Needlesstosay,tamingthisbeastwasthebiggestchallenge.ItiscontrolledoverthenetworkwithacustomprotocolcalledeISCP,andsupportsbroadcastingofstatechangeevents.
EpsonEH-TW5910:AprojectorfromEpson'sHomeCinemalineup.ItofferstheviewroomfullHDvisuals,inboth2Dand3D.ItcanbecontrolledthroughRS-232serialcommunication,buttomaintainalightweightandrelativelyportableproductthechoicewasmadetouseinfraredremotecontrol.
AppleTV-3rdGeneration:ThisdigitalmediaplayermadebyAppleismainlyusedforstreamingcontentfromcomputersonthelocalnetwork(e.g.presentations)orfromonlinemediaproviders(e.g.Netflix).Controlwasachievedthroughinfraredcommunication.
TelenetDigicorderAD2200:Telenet'sset-topboxbringsdigitaltelevisiontotheviewroom.Itiscontrolledthroughinfraredremotecontrol,butusesanuncommonprotocolwhichmadeitabitmorechallengingtogetworking.
Context
5
WeMoInsightSwitch:WeMoswitchesarenetworkconnectedsmartpoweroutlets.TheInsightlineofproductsincludethetrackingofstatisticssuchpowerusageandon-offtimes.Intheviewroom,aWeMoInsightswitchcontrolsvariouslights.TheycanbecontrolledoverthenetworkthroughUPnP,andalsoallowsubscriptiontoeventstoenablestatetracking.
Spencer
OneofNovemberFive'sinnovationsisaproductcalledSpencer,amobileworkplaceassistant.Spencerconsistsofan'intelligentcloudlayer'andamobileappthataimstocombineallkindsofenterprisetools,programsanddataintoasingleinterfaceforacompany.OneespeciallyinterestingfeatureofSpenceristheintegrationofIoTdevices,suchascontrolofofficedomoticsandtelemetry.ThereforeoneofthefeaturesexpectedfromthisprojectwasintegrationofaSpencer-compatibleAPI,sothatNovemberFive'semployeescouldcontroleverydeviceintheviewroomfromwithintheSpencerapp.
HardwareRequirements
Thehardwarerequirementsforthecontrolpanelitselfincludedthefollowing:
8pushbuttonsthatcouldbemappedtopresets.8RGBLED'sthatcorrespondtothesepresets,andshowtheactiveone.AnOLEDdisplaythatprovidessomebasicinformationtotheuser.Arotaryencoderwithbuilt-inpushbuttonasinputdevicesotheusercaneasilychangethemostusedsettingssuchaspowerandvolume.
Aftercreationandevaluationofaworkingprototypeonabreadboard,anactualproductwouldbedesigned.Thisincluded2additionalbigtasks:
ThedesignandassemblyofaPCBtoreplacethebreadboardprototype.ThisPCBshouldusesurface-mountdeviceswherepossibletosaveonspaceandcost.ThedesignofanicelookingandsuitablecasingthatcouldhousetheassembledPCBandallattachedhardware.
Context
6
Scenarios&Presets
Asstatedbefore,oneoftherequirementswasthatthemostcommonsetupscouldbeactivatedwithasingleactionoftheuser,theso-calledpresets.IntheendthesepresetswouldbereprogrammablethroughSpencer,butintheearlyrequirementsthefollowingcommonsetupsweredefined:
CaféAppstrakt/NovemberFive:Thiswere3slightlydifferentpresetsmeantforpresentationsduringthemonthlyCaféevents.Theyincludedturningontheprojector,settinguptheaudioforzones1and2,andsettingthevideosourcetoeithertheAppleTV,HMDIport,orVGAconnectordependentonwhatthepresenterwanted.
CinemaAppstrakt/NovemberFive:Asthenameimplies,thispresetwasmeantforwatchingmovies.Itpoweredtheprojector,selectedtheAppleTVasvideosourceandsetupsurroundsoundaudioandvideoinzone1.
TV:Closelyresembledthecinemapreset,butpoweredandconfiguredtheTelenetDigicorderinsteadoftheAppleTV.
Gaming:Poweredtheprojector,changedthevideosourcetotheconnectedPlaystation4,andsetupaudioandvideoaccordingly.Inthebeginningthisalsochangedtheaudiomodetoaspecialbuilt-ingamingsurroundsoundmode,butforunknownreasonstheA/Vreceiverwouldalwaysoverridethissettingafteracoupleofseconds.
Fitness:Thispresetwasmeantfortheusersofthefitnessroom,whichwasrightnexttotheviewroom.Itsetupaudioonlyforzone2.
Party:Thelastpresetwaspartymode,whichconfiguredaudioforzones2and3.
Context
7
SoftwareEachdeviceintheviewroomcommunicatesusingitsownprotocol,e.g.theOnkyoreceiveruseseISCP,WeMoswitchesuseUPnP,andtheotherdevicesusedifferentkindsofinfraredremotecontrolprotocols.Inordertomakedevelopment,testingandmaintenanceoftheendproducteasier,itwasnecessarytoencapsulatealltheseprotocolsinasinglehigh-levelAPI.Takingintoaccountthattheendproductwassupposedtobeanembeddedcomputer,alightweightenvironmentwasneededthatcouldbothrunthishigh-levelAPIandprovideaneasywaytomaintainthesoftware.
Chapter4.1:Environmentisdevotedtothedesignchoices,setupandconfigurationofthesystemandenvironmentthatruntheviewroomcontroller.
Chapter4.2:Controllingtheviewroomdelvesfurtherintothedifferentprotocolsusedintheviewroom,andexplainsthearchitecturewithwhichthesedifferentprotocolswerecombinedintoasingleAPI.Therestofthischapterhandlessomeoptimizationsinbothefficiencyandreusabilityofthecreatedsoftware.
Context
8
Environment"Itisunfortunatethathestillhasnonfreesoftwareinhiscomputer.Heneedstodefenestrateit(whichmeans,eitherthrowWindowsoutofthecomputerorthrowthecomputeroutofthewindow)."–RichardStallman
TheCaseforArchLinuxDuringexploratoryresearchitwasdiscoveredthatalldevicesintheviewroomcouldbecontrolledthrougheitherinfraredremotecontrolsignalsoranAPIwritteninpython,java,orotherhighlevelprogramminglanguage.Inordertoutilizethesehigh-levelinterfacesandmakedevelopmentcomfortablethechoicewasmadetouseaRaspberryPiasembeddedcomputer(amongotherreasons,discussedindepthinthechapter'Design&Prototyping').TheRaspberryPioffersmanydifferentoptionsfortheoperatingsystemincludingmultipleGNU/Linuxbaseddistributions,RISCOS,orMicrosoftWindowsIoTCore.
WindowsIoTCoreisMicrosoft'sOSforembeddedsystemdevelopment.Ithasmultipleproblemsthatdidn'tmakeitsuitableforthisproject.Firstandforemost:itcan'tbeconsideredastandaloneoperatingsystem.It'snotpossibletoattachakeyboardandscreenandbootintoWindowsIoTCoreanddoanythingusefullikecompileorinstallsoftwareorconfigurethesystem.Instead,anexternalWindowssystemwithMicrosoftVisualStudioisneededtoconfigureandprogramtheWindowsIoTCoredevice. Thisbringsupthesecondpoint:NotonlydoesitcostmoneytolegallydevelopforWindowsIoTCore(Windows,VisualStudiolicensing),butnoneofthefourfreedomsaccordingtotheFreeSoftwareDefinitionarerespectedmeaningthatanyproductmadewithWindowsIoTCoreisinherentlyharmfultotheenduser's(andinthiscasealsothedeveloper's)freedom.Lastly,thecommunitysupportforthisoperatingsystematthetimeofwritingissmallbecauseit'ssonew,especiallyincontrasttoGNU/Linux-basedoperatingsystemswhichhaveexistedforover20years.
RISCOSisasingle-userOSfirstreleasedin1987specificallydesignedtorunontheARMarchitecture. RISCOSisaveryinterestingprojectfromahistoricalandeducationalpointofview,butitlackedtoomanyimportantfeaturesandsoftwarepackagestoconsideritforthisproject.Forexample,therewerenoinfraredtransmitterdrivers,andthelastavailablepythoninterpreterbinaryforRISCOSwasversion2.4.1Betareleasedin2005.
Withtheseoperatingsystemsoutoftheway,thechoicebetweenmanydifferentGNU/Linuxbaseddistributionsstillhadtobemade.TheRaspberryPiFoundation'sofficiallysupporteddistributionisRaspbian,basedonthepopularDebianLinuxdistribution. Raspbianisafixed-releasedistributionwithastrongfocusonstabilityandcomeswithalotofpre-installedsoftwareforeducation,programming,andgeneraluse.OtherOSoptionsfortheRaspberryPiincludeUbuntuvariants,mediacenterorienteddistributions,andmanymore.
ForthisprojectArchLinuxARMwaschosen,anOSbasedonArchLinuxthat'scompatiblewiththeARMarchitecture.It'sbuilton5coreprinciples:Simplicity,modernity,pragmatism,usercentralityandversatility. Theresultisaverylightweight,fastandup-to-datebasesystemthatcan(andshould)beconfiguredspecificallyaccordingtoitsfunctionandtasks.ThatwasexactlythereasonthatmadeArchLinuxARMagreatchoiceforthisproject:TheOSdidn'tbringalotofoverheadwhichbenefitsperformanceandpowerconsumptionandthelatestandgreatestsoftwarewasalwaysavailable.Anotherreasonforthischoicewasmypersonalexperiencewith-andlovefor-ArchLinuxasalongtimedailyuser.Thesetup,configuration,andrelateddecisionsaredescribedindetailintheappendix'ArchLinuxARMsetupandconfiguration'.
1
2
3
4
5
6
Environment
9
DependenciesNexttoaproperlyconfiguredOS,certainsoftwarepackageswereneededtodevelopandruntheproject:
Python3.x
package:python
Pythonisahigh-level,general-purpose,interpreted,dynamicprogramminglanguage. AllsoftwareontheRaspberryPithatwascreatedforthisprojectwaswritteninPython.ThemainreasonswerethatboththeOnkyoreceiverandtheWeMoInsightswitcheshadAPI'savailableforthePythonlanguage,andit'saverywellsupportedlanguageonRaspberryPi-likeplatforms.
Python3.xisthepresentversionofthelanguage,butbecauseitbroughtquitesomechangestothelanguageinrelationtothe2.xversionstherewasalotofdiscussionaboutwhichwasbetter.Python2.xisstillofficiallysupporteduntil2020andhasthemostpackagesandmodulesavailable,whilePython3.xisconsideredthefutureofthelanguageandbringsimprovementsthatweren'tpossibleinthelegacyversions.ForthisprojectPython3.xwasusedasitwasconsideredthemodernversion,andtherewastimetoportlegacypackagestothenewerstandardifnecessary.
Gevent
package:python-gevent
Geventisanetworkinglibrarythatusesthehigh-performanceeventloopfromthelibevlibraryunderthehood. It'sadependencyoftheouimeauxlibrary,whereitisusedtosetupTCP/IPsockets.
LXML
package:python-lxml
Thispythonlibraryuseslibxml2andlibxslt-2widelyusedClibraries-toparseHTMLandXMLdata. ThisprojectusesLXMLtocreateandparsemessagestoandfromWeMoswitches,whichusetheXML-basedSOAPprotocol.
PySerial
package:python-pyserial
PySerialisawidelyusedpythonlibrarythatallowscommunicationoverserialconnections. ItwasusedinthisprojecttocommunicatebetweentheRaspberryPiZeroandtheexternalmicrocontroller.
Netifaces
package:python-netifaces
ThePython'netifaces'librarymadeiteasytocheckwhethercertainnetworkinterfaceswereup,configured,andconnected.Thiswascrucialinformationtoruleoutnetworkerrorsifsomethingwentwrong,ortoshowthesystemstatustotheenduser.
7
8
9
10
11
Environment
10
LIRC
package:lirc
TheLinuxInfraredRemoteControlpackagecontainstoolstoread,transcode,andemitallkindsofinfraredremotecontrolsignals. Theincludedirrecordprogramwasusedtorecordallnecessaryinfraredsignalsusedintheviewroom.Theirsendprogramwasthenusedtoemitthesecapturedsignalsagainwhenasked.LIRCcanuseallkindsofplug-and-playIRdevicestoreceiveandemitsignals,butfortheviewroomcontrolleracustomcircuitwasdesigned.ThiswaspossiblebecausetheLIRCpackageincludesaspecialkerneldrivermodulecalledlirc_rpiwhichallowsittodirectlycontrolIRsensorsandLED'sconnectedtotheGPIOpinsonaRaspberryPi.
Git
package:git
GitisadistributedversioncontrolsystemoriginallydevelopedbyLinuxkerneldevelopersfortheirworkontheLinuxkernel. Itwasusedextensivelyduringthedevelopmentoftheproject,aswellasthewritingofthisthesis.
GNUscreen
package:screen
ScreenisaterminalmultiplexeroriginallydesignedbyOliverLaumannandCarstenBormannin1987,andcurrentlymaintainedbyAmadeuszSławińskifortheGNUproject. Aterminalmultiplexermultiplexesasingleterminalbetweenmultipleprocesses,itcanbethoughtofasawindowmanagerinatext-onlyenvironment.WhilescreencameinveryhandyduringgeneraluseoftheRaspberryPi,thisprojectuseditfor2specificpurposes:
Screencandirectlyopenserialconnectionstoattacheddevices,whichmadedebuggingofexternalmicrocontrollerseasy.E.g.screen/dev/ttyUSB09600opensthefirstUSBserialconnectionwithabaudrateof9600.ThePythonprogramthatcontrolsalldevicesintheviewroomoffersaninteractivecommandlineinterfacetotheuser.Sincethisprogramispermanentlyrunningasadaemonandatextterminalcanonlyshow1processatatime,itwould'vebeenimpossibletosimultaneouslyruntheprogramandabashshellforexample.ScreenallowsustoruntheprograminthebackgroundandopentheinteractiveCLIatanytimebyrunningscreen-r(-r=reattach).Whendone,theprogramcanbesentbacktothebackgroundwiththeCtrl-adcommand(d=detach).
Supervisor
package:supervisor
Supervisorisaprocesscontrolsystemthatmonitorsandcontrolssubprocesses. EventhoughthisisafeaturethatisnormallymanagedthroughtheOS,e.g.systemdonArchLinux,SupervisorwasrecommendedbycolleaguesatNovemberFiveastheyuseitinseveralcriticalpartsoftheirworkflow.Inthisprojectitwasresponsibleforstartingtheviewroomcontrolsoftwareonbootandmakingsurethatitrestartedifacrashwouldhappen.
12
13
14
15
16
1
Environment
11
.https://www.raspberrypi.org/downloads/↩
.https://ms-iot.github.io/content/en-US/win10/StartCoding.htm↩
.https://www.riscosopen.org/wiki/documentation/show/HomePage↩
.https://www.python.org/download/other/↩
.https://www.raspberrypi.org/downloads/raspbian/↩
.https://wiki.archlinux.org/index.php/Arch_Linux↩
.https://en.wikipedia.org/wiki/Python_(programming_language)↩
.https://hg.python.org/peps/rev/76d43e52d978↩
.http://www.gevent.org/↩
.http://lxml.de/↩
.https://github.com/pyserial/pyserial↩
.http://lirc.org/↩
.http://aron.ws/projects/lirc_rpi/↩
.https://git-scm.com/↩
.https://www.gnu.org/software/screen/↩
.http://supervisord.org/introduction.html↩
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Environment
12
Controllingtheviewroom"Oneofmymostproductivedayswasthrowingaway1,000linesofcode."–KenThompson
BuildingblocksTheriseofthehackerandmakermovementsovertheyearsbroughthugeamountsofopensourcehardwareandsoftwareprojectstothemasses.Atthesametimemanycompaniesfoundvalueinexposinganinterfacetotheirproductsandallowingthirdpartydeveloperstoimproveorextendthem.Asaresult,API'sand/orhardwarehackscanbefoundforalmosteverydeviceimaginable.Luckily,thiswasalsothecaseforthedevicesintheviewroom.Thefollowingparagraphswillexplainhoweachdeviceiscontrolled,andhowthesebuildingblockswereintegratedintheendproduct.
OnkyoA/VReceiver
ManyreceiversmadebybothOnkyoandIntegraoffercontrolovertheIntegraSerialControlProtocol(ISCP),whichalsohasanetworkimplementationcalledISCPoverethernetoreISCP.Onkyooffersverycompleteandcleardocumentationabouttheprotocol ,butthiswasonlynecessarylaterinoptimizingthesoftwareasapythonimplementationalreadyexisted:onkyo-eiscp.
Thislibraryprovidedfunctionsfordiscoveringreceiversonthenetwork,settingupaconnection,andsendingandreceivingeISCPmessages.Italsohadanexperimental'async'implementationthatincludedabackgroundlistener,whichisveryusefulasthereceiversendsoutupdatenotificationwheneverasettingchanges.WhilethislibrarywascrucialtoprototypeandtogettoknowthereceiveranditseISCPprotocol,itoftenfailedoncertaincommand-parsingbugs,theexperimentalasynchronousimplementationwasquestionable,anditwasalsoincompatiblewithpython3.x.BecauseofthesereasonsacompletelyneweISCPlibrarywaswrittenforthisproject,whichisdescribedin'Optimizing&packaging'
WeMoInsight
WeModevicesusetheUPnPsetofnetworkingprotocolstoestablishconnectionsandcommunicatewithotherdevicesoverthenetwork.ThereweremultiplepythonlibrariesavailablethatimplementtheUPnPprotocols,butperhapsthemostinterestingwas'ouimeaux'whichisspecificallyaimedattherangeofWeModevices. Thislibraryofferedallthenecessaryfeaturessuchasdevicediscovery,control,andeventsubscriptionandworkedperfectly.Thebiggestdownsidewasthatit'sahugelibrarywithmultipledependenciesthat'scompletelyoverkilliftheonlygoalistoacquirecontrolandtelemetryoftheWeMoInsightintheviewroom.Anotherdownsidewasthatthislibrarywasalsoincompatiblewithpython3.x,luckilyitwaslicensedfreesoftwareundertheBSDlicensegivingthepossibilitytoportitandslimitdownforthisproject.Againthiswillbediscussedlater,in'Optimizing&packaging'.
Infrareddevices
TheEpsonprojector,TelenetDigicorderandAppleTVwereallcontrolledthroughinfraredremotecontrol.Whileeachofthesedevicesusesadifferentinfraredprotocol,controlhappenedthroughasingleinterfaceastheLIRCpackagehandlesalltheusedprotocolstransparently.LIRCautomaticallydiscoversandconfiguresremotecontrolprotocolswhileusingthebuilt-inirrecordprogram,andstoreseverythinginconfigurationfilesperdevice.Theseconfigurationfileswerecreatedforthenecessarydevicesandarestoredwithintherepository.
WithinapythonenvironmentLIRCcouldbecalledbyusingthenativesubprocessmodule.Thismoduleallowspythontostartanyprogramasasubprocessofthepythoninterpreter,connecttoinput/output/errorpipes,andobtainitsexitcode. Soforexampleiftheprojectorshouldbepoweredonfromwithinpython,apythonsubprocessiscreatedthatrunstheirsendprogramwiththeappropriateargumentsandanexitcodeofzeroisexpectedtoindicatesuccess.
12
3
4
Controllingtheviewroom
13
Theproblemwiththeinfraredcontrolleddeviceswasthattherewasnopossibilityoftrackingtheirstateasthecommunicationisonewayonly.Thiswasn'tabigdealinmostcasesexceptfortheTelenetDigicorder,whichonlyhasacommandtotogglethepowerinsteadofexplicitonandoffcommands.ThismadeitpossiblefortheviewroomcontrollertogetoutofsyncifsomeonemanuallytoggledtheDigicorderpowerusingtheremotecontrolorthepowerbuttononthedevice.IntheendproducttheprogramwouldjustassumethattheDigicorderisoffunlesstheprogramitselfexplicitlytoggledthepowerbeforethroughacommandorpreset.
UnifiedarchitectureFindingandtestingthesebuildingblockswastheeasytask,themainchallengewasdesigningacleanandwellperformingarchitecturethatcombinedallthesedifferentdevicecontrolmethods,andexposingthattotheenduser.Thefirststepwastoresearchsuitabledatastructuresanddesignpatternstotacklethischallenge.
DesignPatterns
Thecommandpatternseemedlikeagoodstartingpointasitencapsulatesallinformationnecessarytoexecuteaspecificcommand. Thiswouldallowtheusertoinputanycommand-likeobjectthatrepresentsthedesiredaction,andthecommandpatternimplementationintheprogramwouldlinkthatcommandtothedesireddeviceanditsspecificAPIcall.ThiswouldeliminatetheproblemofhavingadifferentAPIforeachdevice.
AccordingtotheUNIXphilosophytextstreamsandstringsaretheuniversalinterface andthepythonlanguagehasexceptionalstringmanipulationcapabilities ,sostringswerechosenastheinternalwayofhandlingcommands.Thiswaytheusercouldinputhuman-readablecommandsthroughavirtualterminal,whichcouldbeprocesseddirectlybytheprogram.ThesamewastruefortheexternalmicrocontrollerwhichcommunicateswiththeprogramoverUART,asmostUARTsoftwareimplementationsinterpretdataascharacterarraysorstringsobjectsautomatically.
Withstringsasinputinterfaceandthecommandpatterntoencapsulateactions,thelastmissingpieceofthepuzzlewasdefininganefficientstructurethatcouldlinkastringtotherightcommand.Thechain-of-responsibilitypatternwastheidealsolution:Itmodelscommandhandlersinatreestructure('treeofresponsibility')andletseachnodedefinewhatcommandsitcanhandleandhowitshouldhandlethemordispatchthemtoothernodes. Inthiscasetheviewroomcouldbeseenastherootnode,witheachdevicebeingabranchwithknowledgeaboutthecommandsitcanhandleandchildnodesthatrepresentthedifferentactionsforthedevice.Adiagramwillmakethisclear:
5
67
8
Controllingtheviewroom
14
Implementation
Pythonisgreatathandlingcollectionsandthelanguagehasalotofbuilt-infeaturestoworkwiththem,however,itdoesn'tincludeatreedatastructure.Luckily,thenativedictionarydictallowsitsvaluestobeofanytypemakingitpossibletocreateourowntreestructurebynestingdictobjects.Bysubclassingthenativedictionaryandgivingitanexecute()function,abasicimplementationofthechain-of-responsibilitypatternwasachieved.Thisleadtoatreethatautomaticallyparsesandexecutescommandsrecursivelybyusingthedictionary'skey-valuepairstolinkacommandkeywordtoacommandnode.Again,adiagramwillmakethisclear:
Eachnodeinthistreeisfreetooverridetheexecute()function,tofilterormodifycommandsbeforepassingthemonforexample.Thenodeswithoutanychildnodes(calledleafnodes)overrideitwiththeactualconcreteactionthatneedstohappen.Thecompletedcommandtreeintheendresultconsistedofalmost300nodes,whichisnotthatsurprisingknowingthateachofthe3zonesoftheOnkyoreceiveralreadycontributedmorethan50nodes.
Throughtheuseofsubclassing,newnodescouldbemadeeasilyandfast.TwosuchsubclasseswereOnkyoCommandandLircCommand,whichformedthebaseforISCPandinfraredcommandsrespectively.Theyimplementedtheexecute()functionfortheirservicesbymakinguseoftheirownkey-valuepairs(recallthateachnodeisasubclassofdict),sothatchildclassescouldcreatefullyfunctioningnodeswithouthavingtore-implementprotocol-specificlogic.Therearemanyexamplesofthisinthecodebase,ashortandsweetoneisthefollowingsub-nodeofLircCommandthatparsesandhandlespowercommandstotheprojector:
classBeamerPower(lirc_node.LircCommand):
def__init__(self):
super().__init__("Beamer")#Name=identifierforLIRC.
#Commandkeyword->LIRCparameter
self["on"]="KEY_POWER"
self["off"]="KEY_POWER2"
Ifanode'sdefaultexecute()functiondoesn'tknowwhattodo,itwillraisethecustomNonExecutableNodeErrorwhichcontainsthenameofthenode,theargumentthatwasn'tunderstood,andalistofargumentsthatareactuallyexecutableoratleastpassablebythatnode.Thishelpedalotduringdebugging,orwhenusingtheprogramthroughitscommandlineinterfaceandtypingamistake.Thisexampleoutputoftheprogramwillhelpillustratethis:
Controllingtheviewroom
15
>>viewroombeamerpowerof
[!]NonExecutableNodeError:Didnotreachexecutablenode!
Unrecognizedoption:of
Optionsat'power':
-on
-off
Presets
Beforepresetswerehandledinthebackend,asimpleJSON-basedpresetsystemwasimplementedintheprogram.Suchapresetconsistedof2fields:'name'whichisasimplestringtoidentifythepresetwith,and'actions'whichwasanarrayofcommandstoexecute.E.g.:
{
"name":"gaming",
"actions":[
"viewroombeamerpoweron",
"viewroomonkyoz1poweron",
"viewroomonkyoz1inputbd-dvd",
"viewroomonkyolistening-modesurround",
"viewroomonkyoz1muteoff",
"viewroomonkyoz1volume50"
]
}
Toreducetheamountofdoubletextintheactionssection,commandscouldbenestedasfollows:
{
"name":"fitness",
"actions":[
{"viewroomonkyoz2":
["poweron","inputcbl-sat","muteoff","volume65"]}
]
}
DuringinitialtestingitwasdiscoveredthattheOnkyoreceiverwouldskipcommandsiftheywereexecutedconsecutivelywithoutacertaindelay.TheeISCPdocumentationspecifiesadelayofatleast50milliseconds ,butthroughexperimentationadelayofatleasthalfasecondwasfoundtobemorestable.Theresultwasthatworkingpresetslookedliketheexamplebelow.Integrationwiththespencerbackend(whichisdiscussedinthe'Firmware'chapter)madetheJSONpresetsobsoleteastheywouldbedefinedandexecutedfromtheSpencerbackend.
{
"name":"cafe-hdmi",
"actions":[
"viewroombeamerpoweron",
"viewroomonkyoz1poweron",
"delay0.5",
"viewroomonkyoz1inputport",
"delay0.5",
"viewroomonkyoz1muteoff",
"delay0.5",
"viewroomonkyoz1volume65",
"delay0.5",
"viewroomonkyoz2poweroff"
]
}
1
Controllingtheviewroom
16
Optimizing&packagingTheimplementationofthedesignpatternsdescribedaboveresultedinacleanarchitecturethatallowedcontroloftheviewroom.However,thesystem(andbyextensiontheuser)hadnoideawhatthestateofthedeviceswas,leadingtounnecessaryactionsandbaduserexperience.Forinfrareddevicesthiswouldalwaysbeguessingworkastheinfraredremotecontrolprotocolsusedinthesedevicesallowone-waycommunicationonly.ThereceiverandWeMoswitchesontheotherhandcansendoutstatechangeeventsoverthenetwork,makingitpossibletoalwayskeepthesystemanduseruptodate.
Listeningandwaitingfornetworkeventsimpliesanetworksocket,daemonprocess,and/orasynchronouscode.Allthreewereusedinaself-writtenmultiprocessing-basedsocket-capableasynchronouscommunicationmodulecalledcomm_subprocess.
Creatingcomm_subprocess
Python3.xbroughtgreatlyimprovedasynchronouscodehelperssuchastheasyncio andconcurrent.futuresmodules,butPython'sdefaultimplementation(CPython)stilluseda'GlobalInterpreterLock' .Thismeantthattheinterpretercouldonlyrunononenativethreadatalltimesbecauseofmemorymanagementthatisnotthread-safe.Theresultisthat'multithreaded'pythoncodewillallowasynchronouscode,butinrealityisstillconstrainedtoasinglenativethread.AnotherresultisthattheGILactuallydegradesperformancewhenwritingmultithreadingcodebecauseoftheoverhead.
ThePythondocumentationsuggestedusingthemultiprocessingmoduleasasolutioniftruemultithreadingandmultiprocessingarerequired.ThismodulecouldspawnnewPythoninterpretersassubprocessesanddispatchcertainpartsofcodetothesesubprocesses.BecauseeachPythoninterpreterhasitsownnativethread,actualmultiprocessing(andthusbetterperformance)couldbeachieved.Thisprovedtobeagreatsolution,butwritingthesamebasicsubprocessmanagementcodeforeachandeveryasynchronousinterfacewouldbetimeconsuminganddumb.Amodulecalledcomm_subprocesswascreatedtoprovideabaseonwhichtruemultiprocessedcommunicationclassescouldbebuiltquicklyandeasily.
Tousethemodule,theincludedCommSubprocessclasshadtobeinheritedandfollowingfunctionsoverridden:
connection_setup():Thisfunctionshouldsetupaconnectionoverwhichcommunicationwilltakeplaceincasethisisnecessary.Thiscodewillbeexecutedinthemainprocess,rightbeforethesubprocessesarecreated.send_msg_over_connection(message):Thisfunctiontellsthemodulehowamessagecanbesentovertheconnection.Ifnecessarythemessagecanbeconvertedtobytesorcertainheaderscanbeaddedforexample.Thisfunctionalwaysrunsinasubprocess,sowillrunasynchronouslyfromthemainprocess.receive_msg_over_connection():Thisfunctiondescribeshowthesubprocessshouldlistenformessages,e.g.throughapollingmechanismontheconnection,orbywaitingforacertaincontrolcharacter.ItshouldreturnamessagewhenitiscompleteoraNoneobjecttoskipthislooponce.Itwillalwaysruninalooponthesubprocessesandthusneverblocksthemainprocess.on_message_received(message):Thisfunctionwillbecalledwheneveracompletemessageisreceived(themessageparameter).Itexecutesinthemainprocesssotherearenoworriesaboutmemorysafety.Incasepre-parsingfunctionsarenecessaryandneedtohappenasynchronously,thesecanbeincludedinthereceive_msg_over_connection()function.
9 1011
12
Controllingtheviewroom
17
Thecomm_subprocessmodulewouldthenhandlethecreationandmanagementofthesubprocessesbehindthescenes.Bycallingtheconnect()functiontheconnectionwouldbesetupandasubprocesswouldbecreated,alongwithapipetothissubprocesstocommunicatebetweenthetwo.Thesubprocessruns2threads(butmultiplexedduetoGIL):onetoconnectthepipetothesendingendoftheconnection(withthesend_msg_over_connectionfunction)andonetoconnectthispipetothereceivingendoftheconnection(receive_msg_over_connection).Athreadinthemainprocesshandlescommunicationoverthispipeasynchronously.ThesubprocessandallparticipatingthreadswatchaPythonThreading.Eventobject calledstop_flag.Ifthedisconnect()functioniscalledoranexceptionoccursinanyoftheparticipatingthreads,thisstop_flagissetandallthreadsandthesubprocessattempttofinishtheiractions,closeconnections,stop,andjointhemainprocess.
Thefinalimplementationofcomm_subprocessworkedgreat,allowingtocreateveryefficientcommunicationdaemonswithease.AnexampleistheSerialAsyncclasswhichhandlesmultiprocessedcommunicationwiththeexternalmicrocontrolleroverUARTinbarely40linesofcode.
RecreatingOnkyo-eISCP
Itwasstatedbeforethattheonkyo-eISCPlibraryperformedsuboptimal,theasynchronousimplementationwasexperimental,anditwasn'tcompatiblewithPython3.Luckily,itsMITlicensepermittedtoresearch,modify,useandre-releasethecode.Thenewmultiprocessingmodulewasthesolutiontothefirsttwoproblems.Firstly,theeISCPprotocolwasresearched,debuggedandimplementedwiththehelpofOnkyo'sdocumentation andWireshark.
SettingupanIPnetworksocketforeISCPinthesubprocesswasabreezewithaPythonsocketobject ,makingitpossibletoreceiveallstatusupdatessentbythereceiveraswellasconstructandsendpacketswithinthesubprocess.ThereceivedeISCPpacketswereparsedinthesubprocesssoonlytheactualISCPcommandremained(e.g.:PWR00,MVL22,...),whichwasthenpassedtothecommandtree.EachOnkyocommandnodealreadyknewitsownISCPcommandkeyword(e.g.:PWR,MVL,...)tosendcommands,solettingthetreeparseandstorethemtooseemedlikealogicalchoice.Anextracommandviewroomonkyostatuswasadded,whichprintedasummaryofthestatusinaclearandreadableway,includingthepower,volumeandsourcesofthedifferentzones.
PortingthemoduletoPython3wasn'tveryhardeither,asitdidn'thaveanyexternaldependenciesoruseanydeprecatedfunctions.Thebiggesttaskwasadaptingthesyntaxchangessuchasprint()nowusingthefunctionsyntax,stringsbeingunicodebydefault,andnewexceptionhandlingsyntax.
ThisneweISCPlibrarywascalledonkyo_commasareferencetotheoriginalonkyo-eISCPmoduleandthenewcomm_subprocessmodule.Whilesimpleusageprovedittobemorestableandabitfasterthantheoriginallibrary,itwasalsolessuserfriendlybecausesomehelperfunctionswereleftoutandthecommandswouldbehardcodedinsteadofparsedfromanexternalfile.
RecreatingOuimeaux
TheOuimeauxlibraryalsoneededaporttoPython3,whichwasallowedbytheBSDlicense.ItprovedmuchmoredifficulttoporttothemodernPythonversions,notonlybecauseofitshugecodebasebutalsobecauseofmultipledependenciesanddatafiles.
OuimeauxgetsapartofitsAPIfromXMLschemafiles(.xsd)asWeModevicesuseUPnP,whichinturnusestheSimpleObjectAccessProtocol(SOAP),whichusesXMLbasedmessagesanddatastructures.Theseschemafileswerepartofthelibrary,andwereconvertedtoPythonclassesandfunctionswithatoolcalledgenerateDS.py inordertobeusedbythePythonscripts.TheoriginallibraryusedgeneratedstructuresthatwereonlycompatiblewithPython2,sothefirststepwastoregeneratethemforPython3byusingthelatestversionofgenerateDS.py.
13
1
14
15
16
Controllingtheviewroom
18
Ouimeauxalsodependedonpysignals,asignaldispatchermodulethat'spartofthepopularDjangowebframework.pysignalswasnotaseperatelydevelopedmodule,someonenamedTheoJuliennejustextractedthecodefromtheDjangoframeworkandpublisheditasastandalonepackage. Developmentand/ormaintenanceofthemodulequicklyhalted,andtheouimeauxprojectwasstuckusingaworkingbutdeprecatedmodulethatwasn'tcompatiblewithPython3.Theexactsameapproachwasusedtorecreateouimeauxforthisproject:ThelatestPython-3compatibleDjangoreleasewascloned,theup-to-datepysignalsextracted,andimplementedinthecustomouimeauxclone.ThiswasalegalmoveunderthetermsofDjango'sBSDlicense.
MostoftheworkthatremainedafterthiswasapplyingthesamesyntaxchangesaswiththeOnkyo-eISCPrewrite.However,theouimeauxlibrarycontainedalotoffeaturesthatwereunnecessaryfortheviewroomcontrollerandwouldtakealotoftimetoport,e.g.:standaloneCLItoolandwebserver+interface.Thesefeatureswereleftout.
Packaging
Inordertogivebacktothewonderfulfreeandopensourcesoftwarecommunity,every(re)createdmodulethatcouldbereusedwaspackagedaccordingtothePythonpackagingstandards andwould(re)releasedunderafreesoftwarelicense .Asthiswasnotwithinthescopeoftheprojectandtimeisneededtogetcodequalitytoacertainstandardandcomplywithsoftwarelicenses,thiswasstillaworkinprogressatthetimeofwriting.
16
1718
1
Controllingtheviewroom
19
.http://michael.elsdoerfer.name/onkyo/ISCP-V1.21_2011.xls↩
.https://github.com/miracle2k/onkyo-eiscp↩
.https://github.com/iancmcc/ouimeaux↩
.https://docs.python.org/3.5/library/subprocess.html↩
.https://en.wikipedia.org/wiki/Command_pattern↩
.http://www.faqs.org/docs/artu/ch01s06.html↩
.https://docs.python.org/3.5/library/string.html↩
.https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern↩
.https://docs.python.org/3/library/asyncio.html↩
.https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures↩
.https://wiki.python.org/moin/GlobalInterpreterLock↩
.http://www.dabeaz.com/python/GIL.pdf↩
.https://docs.python.org/3.5/library/threading.html#event-objects↩
.https://docs.python.org/3.5/library/socket.html↩
.https://docs.python.org/release/3.0.1/whatsnew/3.0.html↩
.https://pypi.python.org/pypi/generateDS↩
.https://python-packaging.readthedocs.io/en/latest/↩
.https://www.gnu.org/licenses/license-list#GPLCompatibleLicenses↩
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Controllingtheviewroom
20
HardwareWiththesoftwareinplace,theenduserstillneededasimpleandintuitivewaytointeractwiththesystem:thecontrolpanel.Thegoalwastocreateauser-friendly,compact,butindependentandcompleteendproduct.Asaresult,everyhardwaredesignchoicehadtobemadewithdimensionalconstraintsandpowerrequirementsinmind.
Chapter5.1:Designandprototypingtalksaboutthecreationofaworkinghardwareprototype,includingtheselectionofcomponents,calculations,testsandmeasurements.
Chapter5.2:FirmwarehandlestheC/C++softwarethathandleslow-levelcontrolofthehardwarecomponents,aswellasthebackendintegration.
Chapter5.3:Buildingtheendproductdescribesthetransitionfromprototypetothefinishedendproduct,mainlythedesignofthePCBandthecasing.
Controllingtheviewroom
21
Design&Prototyping“Nothingisparticularlyhardifyoudivideitintosmalljobs.”–HenryFord
MicrocontrollersTheoriginalrequirementsimpliedthatonemicrocontrollerwouldbeusedtohandleboththehardwareandthesoftwareusedtocontroltheviewroom.ARaspberryPi2wasrecommendedforprototypingasitwascheap,available,anddefinitelypowerfulenough.ThiswouldbereplacedbyaRaspberryPiZerointheendproductbecauseofitssmallerfootprint.ThechoicewasmadetoincludeasecondmicrocontrollerandconnectittotheRaspberryPithroughaserialconnection.Thereweremultiplereasonsforasecondmicrocontroller,mostofthemhadtodowitheaseofdevelopment.OnesuchreasonwasthattheNeoPixelRGBLEDstrip'sdataprotocolrequiredveryspecifictiming,whichcouldn'tbeguaranteedbytheRaspberryPibecauseofitsnon-realtimeoperatingsystem.TheRaspberryPiwouldthusrunacompletemultitaskingoperatingsystemofferinghigh-levelprogrammingandafull-blowndevelopmentenvironment,whiletheexternalmicrocontrollerofferedlow-leveldirectcontrolandaccuratetimingwithouttheoverheadofanoperatingsystem.
RaspberryPies
AsecondgenerationRaspberryPiwasusedduringprototyping,mainlybecausetheZeroeditionwasconstantlysoldoutatthetimeandwasonlyavailablehalfwaythroughtheproject.ThetwoversionsoffertheexactsameGPIOpinlayout,andbothcanrunthePythoninterpretersoportingtheprojectbetweenthetwowasstraightforward.Theonlychangenecessarywasareinstalloftheoperatingsystem,asthetwopiesusedifferentprocessorarchitectures.Thesearethebiggestdifferencesbetweenthetwothatmatteredfortheproject:
RaspberryPi2 RaspberryPiZero
CPUArchitecture ARMv7Cortex-A7 ARMv6
ClockSpeed 900MHz 1GHz
CPUCores 4 1
RAM 1GB 512MB
USBports 4 1
Size 85.60mmx56.5mm 65mmx30mm
CurrentDraw 220-820mA 100-350mA
WhiletheRaspberryPiZerowaslesspowerful,itwasalsosmallerandrequiredsignificantlylesspower.TheRaspberryPi2prototypeused2USBports:1foraWi-Fidongle,and1fortheUSBconnectiontotheexternalmicrocontroller,providingpowerandcommunication.TheRaspberryPiZeroonlyhad1micro-USBport,thisproblemwassolvedbypoweringtheexternalmicrocontrollerfromthePi's5Vpin(whichisactuallyconnectedstraighttothePi'spoweradapter )andusingthehardwareUARTpins(TX/RX)ascommunicationinterface.
1
2
3
Design&Prototyping
22
ArduinotoParticle
TheoriginalexternalmicrocontrollerwasanArduinoUno,apopularATmega328P-basedprototypingboard.Availabilityandpersonalexperiencewiththedevelopmentprocessmadethisalogicalchoice.ItwasquicklyreplacedbyaParticlePhoton,aboardbasedontheARMCortex-M3withaBroadcomWi-Fichip. ThischangewassuggestedbecausethePhotonisusedforalotofprojectswithinNovemberFive,andtheyhadalreadymadecodetemplatesforeasyintegrationwiththeSpencerAPIthroughParticle'sbuilt-incloudfunctions.Aquickcomparisonbetweenthesetwoprototypingplatforms,forthefeaturesthatmatteredtothisproject:
ArduinoUno ParticlePhoton
CPUArchitecture 8-bitAVR 32-bitARMCortex-M3
ClockSpeed 16MHz 120MHz
FlashMemory 32KB 1MB
OperatingVoltage 5V 3.3V
DigitalGPIOPins 14(6PWM) 18(9PWM)
ADCInputPins 6 8
Size 68.6mmx53.4mm 36.58x20.32mm
CurrentDraw ~50mA ~100mA
ThecomparisonshowsthatthePhotonoffersalotmorepossibilitiesinasmallerpackage,andwithoutrequiringalotofextrapowerconsideringthatit'sequippedwithaWi-Fimodule.DespitethesedifferencesalmostnochangeswerenecessarytothecodewrittenforArduinoasbothprototypingboardsbasedtheirAPIonthe'Wiring'project. AlllibrariesusedintheArduinocodewereavailableforthePhotonoreasilyportable(mainlybecauseoftheirsimilarAPI).ThefactthattheArduinoisan8-bitplatformwhilethePhotonisa32-bitplatformdidn'tmattereither,asthecodewaswrittenforoptimalmemoryusagefromthestartbyusingexact-widthvariabletypes ,e.g.:'int8_t'insteadof'int'.Andevenwithadifferentoperatingvoltage,hardwarechangeswereminimalasa5VsupplywasstillavailableifnecessaryfromtheRaspberryPi's5Vpowerpin.
PowerConsiderations
TheRaspberryPiZerogotitspowerfromapoweroutlet,andwasthenresponsibletopassthispowertoallothercomponents.Ofcourseeverymicrocontrollerhasitslimitssothepowerusagealwaysplayedanimportantpartduringthedesignphase.ThePiFoundationstatedthatthestandalonePiZerohadamaximumcurrentdrawofabout350mAunderfullload(eventhoughreal-lifetestsneverseemedtoreachmorethan150mA ).TheRTl8188CUS-basedWi-FidonglewastheonlyUSBperipheral,anddrewaround100mAofcurrentunderfullload.
The5VpinsontheRaspberryPiaresuppliedstraightfromthePi'spoweradapterandcanthereforedrawcurrentequaltothepoweradaptersmaxcurrentminusthePi'sownusage.Thesystemmadeuseofa5V2Apowersupply,meaningthatthePi's5Vpinscouldstillprovideabout1.55A(2A-350mA-100mA)underfullload.ThePi's3.3VGPIOpinsaresuppliedthroughtheCPU,sothesehavestrictercurrentlimits.Eachindividualpinshouldneversourceorsinkmorethan16mA,andtheentire3.3Vnetshouldnotexceed50mAofcurrentdraw.
TheParticlePhotonusedaround100mAwiththeWi-Fimodulepoweredonandnothingconnected.It'sa3.3Vmicrocontrollerbutthebuilt-involtageregulatorcanhandle5Vinput,soitwaspoweredbytheRaspberryPi's5Vrail(leavinganother1.45Aforothercomponents).ThePhoton's3.3Voutputnetcansupplyaround100mA,whileeachindividualGPIOpincansupplyorsink25mAandthetotalcurrentdrawshouldnotexceed120mA.Ashortoverviewofthesesourcesasreferenceforthenextchapters:
4
5
4 5
6 7
8
9
1011
12
Design&Prototyping
23
Source Voltage Max.Current
Pi5VPin 5V 1.45A
Photon3.3VPower 3.3V 100mA
Pi3.3V&GPIO 3.3V 16mA/pin,50mAtotal
PhotonGPIO 3.3V 25mA/pin,120mAtotal
InfraredRemoteControlAsdiscussedinthechapter'Environment',theinfraredhardwarewouldbeacustomcircuit.ThemaincomponentsthatwereneededwereanLEDthatemitsinfraredlightwithawavelengthbetween930and950nm ,andasensorcapableofdetectingsuchsignals.ForthesensorNovemberFivealreadyhadtheTSOP34838instock,a3-pinplug-and-playIRreceiverwithfilteringanddemodulationalreadyonboard. ThissensorissupportedbyLIRCandworkswith3.3Vlogic,soitwasconnecteddirectlytotheRasberryPiandworkedflawlessly.
Becausethedevicesintheviewroomarespreadapart,twoLED'swouldbeusedunderdifferentangles.TheinfraredemittingLED'sthatwereinstockwerethe5mmMulticompOFL-5102. Theirviewingangleofonly10°provedtobeonobstacle,thereforetheywerereplacedbytheQED234. Theyperformedbetterwithaviewingangleof40°andcouldtoleratehighermaxcurrentsincasebrighteremissionwasnecessary.Withaforwardvoltageof1.6VitseemedliketheycouldalsobedrivenbythePi's3.3VGPIOpins,howeverthesepinsarelimitedto16mA(withtheentirenetlimitedto50mA)whichisbelowtherecommendedworkingcurrentof20mAperLED.
Toovercomethislimit,anNPNtransistorwasusedtosupplytheLED'sfromthePi's5Vpowerpin.ThetransistorusedwasaBC337becauseofitsavailabilityinthelab. WithaforwardvoltagedropovertheLED'sof2x1.6V=3.2Vandtargetingamaximumcurrentof100mA,aresistorofatleast18OhmshouldbeplacedinserieswiththeLED's(1.8/0.1=18,assumingnodropoverthetransistor'sCE-junction).Whencompletelyfinished,Thecircuitwastestedstartingwitharesistorof100Ohmsandslowlyreducingthisresistancetowards18Ohms.Avalueof47Ohmswaseventuallychosenbecauseitgavegreatresults,drawingacurrentof38mA(1.8/47=0.038)).Apowerratingof72mWwasnecessary(1.8x0.04=0.072),whichwasnoproblemfortheavailable250mWresistors.
Thebaseofthetransistorwasconnectedtoa3,3VGPIOpinthrougharesistor.Thebaseresistorlimitswerecalculatedwiththefollowingvariables:
Base-emittervoltagedrop=0.8VhFE=200Targetmax.collectorcurrent=0.1ATargetGPIOoutputcurrent=0.005A
Rmax=(3.3Vx200)/(5x0.1A)=1320OhmsRmin=(3.3V-0.8V)/0.005A=500Ohms
Avalueof1kOhmwaschosenandworkedperfectly.Powerratingwasnotveryimportantbecauseofthetargetedcurrentofbarely5mAat3.3V,wellbelowthe250mWlimitoftheavailableresistors.
13
14
1516
17
Design&Prototyping
24
Byconfiguringthelirc_rpidrivertousethepinconnectedtothetransistor'sbaseasatransmitter,LIRCcouldnowtransmitallknowninfraredremotecontrolsignalsusingthiscircuit.Duringthetestingofthecircuit,anoscilloscopewasusedtomeasureifthecalculationswerecorrectandeverythingstayedwithinthelimits.ThefollowingimageshowsmeasurementsduringtheAppleTV'Menu'command,theprojector'PowerOn'command,andtheDigicorder'PowerToggle'command.Channel1(yellow)istheoutputofthePi'sGPIOpinwhichisconnectedtothetransistorbase.Channel2(blue)showsthevoltagebetweentheresistorandthefirstIRLED,inrelationtotheground.
Thereadingsandtestsshowedthatthetransistorswitchedexactlyaswanted,exceptthatpeakvoltagedropsovertheLED'sresistorseemedbiggerthanexpected(~2,56V>1.8V).Thiswasattributedtotolerancesandtheveryfastswitchingofthesignal,astheoutputofthe5Vand3.3Vpinsshowedsimilarpeakreadings(~5.5Vand~3.6Vrespectively).Luckily,thenecessaryprecautionsweretakenbypickingthecomponentswithasafetymargininbothvalueandpowerrating.
UserI/O
PresetButtons
Eightbuttonswereneededtoactivatethedifferentpresets.Thelabhadstandardmini-pushbuttonswitches ,sothesewereusedintheprototype.Using8digitalGPIO'sforsimpleswitchesseemedlikeawaste,soan8-stepvoltagedividerwasbuiltwithresistors,withabuttononeachstep.ThesebuttonswereconnectedtoasingleADCpin,sotheresultingvoltagecouldbereadandtranslatedtothebuttonthatwaspressed.Onedownsideofthisapproachwasthatonlyasinglebuttonpresscouldbedetectedatatime,asthebuttononthehigherdividerstepwouldshorttherestofthebuttonswhenpressed.Thisdidn'tmatterfortheviewroomcontrollerasonlyonepresetbuttonshouldbepressedatatime.
Toavoidusingtoomuchpower,a10kOhmresistorwasusedforeachstepofthevoltagedividerwitha100kOhmresistorgoingtotheground.Thiswaythecircuitcontainsattheveryleast110kOhmsofresistance,whichdrawsonly30µA.
18
Design&Prototyping
25
PresetLED's
FortheLED's'NeoPixels'werechosen,whichisthefancymarketingtermfortheWS2812RGBLED'swithintegrateddriver. Thesefull-colorLED'suseaspecialprotocolwhichallowsthemtobeconnectedinseriesandstillbeindividuallyaddressable.Infact,withastrongenoughpowersupplyhundredsofNeoPixelscanbeindividuallydrivenfromasingledatapin. Forthisprojectonly8ofthemwerenecessary,oneforeachpreset.Eachpixeldrawsamaximumcurrentof60mAatfullbrightnessforeachcolor.Sometimewasspentexperimentingandmeasuringwithdifferentcolorsandbrightnessvalues,theresultscanbefoundinthe'NeoPixelcurrentmeasurements'appendix
TheNovemberFivered/orangecolorwasbasedontheRGBcodefoundintheofficialstyleguide,whichwasn'tanexactreproductionbutanicecolornonetheless.Atonly22mAperLEDforaverybrightlightitwasveryusableintheproject.TheNeoPixelsaresupposedtooperateon5Vlogicandwitha5Vsupply,butasimplehackexistedtoenable3,3Vlogic:Bydroppingthesupplyvoltage~0.7Vthroughadiode,the3.3Vlogicfallswithinthe70%offsetofthesupplyvoltage(0.7x4.3=3,01)neededtocontroltheintegrateddrivers. Thisimposedalimitontheamountofpixelsaddressableandthemaximumbrightness,butworkedperfectlyforthiscase.The5VpowerwastakenfromthePi's5Vsupplypin(withthementioneddiodevoltagedrophack),whilecontrolwashandledbyaPWM-enabledGPIOpinonthePhoton.
PushSwitchRotaryEncoder
Therotaryencoderwithbuilt-inpushbuttonwaschosenfromtheBournsPEC11series ,withabeautiful1"solidmachinedmetalknobontop. Thisrotaryencoderhasfivepins:oneisgrounded,twoofthemforsendingsignalsonrotation,andtwothatareshortedwhenthepushbuttonispresseddown.Toreadtherotationaldata,thetwodatapinswereconnectedtoGPIOpinsandtheirinternalpull-upresistoronthemicrocontrollerwasenabled.Thepushbuttonpinswereconnectedlikemostbuttons,makinguseofa100kOhmpulldownresistor.
OLEDdisplay
Adisplaywouldserveasabasicuserinterfacefortheuser.Adafruit'sSSD1306breakoutboardwasavailableinthelabandseemedanexcellentfitfortheproject. It'scontrolledoverSPIandoffers128x32whiteOLEDpixelsofdisplayspaceona~1"screen.Nexttoa3.3Vpowersupplyandagroundconnection,itrequired5pinsfortheSPIcommunicationwiththePhoton.Duringtypicalusageitdrewabout15mA.
19
20
21
2223
24
1
Design&Prototyping
26
.https://en.wikipedia.org/wiki/Raspberry_Pi↩
.https://www.raspberrypi.org/help/faqs/#powerReqs↩
.http://pinout.xyz/pinout/pin2_5v_power↩
.https://www.arduino.cc/en/Main/ArduinoBoardUno↩
.https://docs.particle.io/datasheets/photon-datasheet/↩
.http://gadgetmakersblog.com/arduino-power-consumption/↩
.https://docs.particle.io/datasheets/photon-datasheet/#technical-specification↩
.http://wiring.org.co/↩
.http://www.nongnu.org/avr-libc/user-manual/group__avr__stdint.html↩
.https://raspberrypi.stackexchange.com/questions/26526/current-draw-for-2-0-models↩
.https://wikidevi.com/wiki/User:M86/USB_device_power_consumption↩
.http://www.mosaic-industries.com/embedded-systems/microcontroller-projects/raspberry-pi/gpio-pin-electrical-specifications#rpi-gpio-input-voltage-and-output-current-limitations↩
.https://en.wikipedia.org/wiki/Consumer_IR↩
.http://www.vishay.com/docs/82489/tsop322.pdf↩
.http://www.farnell.com/datasheets/1697427.pdf↩
.https://www.fairchildsemi.com/datasheets/QE/QED234.pdf↩
.http://www.onsemi.com/pub_link/Collateral/BC337-D.PDF↩
.https://www.sparkfun.com/products/97↩
.https://learn.adafruit.com/adafruit-neopixel-uberguide↩
.https://learn.adafruit.com/adafruit-neopixel-uberguide/power↩
.https://learn.adafruit.com/adafruit-neopixel-uberguide/power#driving-5v-neopixels-from-3-dot-3v-microcontrollers↩
.https://cdn-shop.adafruit.com/datasheets/pec11.pdf↩
.https://www.adafruit.com/products/2056↩
.https://www.adafruit.com/product/661↩
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Design&Prototyping
27
Firmware"Regressiontesting"?What'sthat?Ifitcompiles,itisgood;ifitbootsup,itisperfect.–LinusTorvalds
CloudAPIwiththeSpencerbootstrapThroughtheuseoftheARMEABIpackage,C/C++codecanbecompiledforthePhoton'sARMCortex-M3bytheGNUCompilerCollection(gcc).Particlehastheirowninterfaceapplication.h,whichisbasedonthe'wiring'project andexposesalotofhigh-levelhelperfunctionsandclassesforuseonthePhotonplatform.NovemberFive'shardwareteamhadabootstrapprojectwhichusedthesefunctionstoquicklyintegrateIoTprojectsintotheSpencerbackend.Itprovedtobeagreatfoundationfortheviewroomcontroller.
ThistemplateprojectcontainedaclassDevice,whichrepresentedadevicethatcouldbecontrolledbythemicrocontroller.AsubclassofDevicewithauniqueidentifierwasmadeforeachdevice,and2methodswereoverridden:
uint8_texecute(uint8_tservice,uint16_tparameter=0):Inthisfunctionaserviceisanintegerthatislinkedtoaspecificfunctionofthatdevice,e.g.:theOnkyoReceiverdevicehadthe'zone1volume'commandboundtoservice1.Theparameterwasanoptionalparameterfortheserviceincasetheservicerequiredone,e.g.forthevolumecommandthiswasanintegerbetween0and80tochangethevolumeto.Thereturnedvalueindicatediftheservicefunctionsucceededornot,withanon-zerostatusindicatingfailure.
voidloop():Asthenameimplies,thisfunctioncontainedcodethatneededtobeexecutedinsidethemainloop()oftheprogram.E.g.ifadeviceneedstobepolledconstantly.
Afterthedeviceswereinstantiatedtheywerekeptinastd::vector<Device*>collectioninordertoeasilyiteratethroughthem.ThetemplateprojectalsocontainedaCommandandCommandHelperclasstoconstructacommand-likepattern.TheCommandclassholdsadeviceidentifier,serviceidentifier,andoptionalparametertodefineacommand.TheCommandHelperclassholdsthecollectionofdevicesandisabletolinkaCommandobjecttoanactualdeviceandexecuteitsservice.
WiththehelpoftheParticle.function()call,itbecamepossibletocalltheintexecuteService(Stringparams)functionthroughaRESTAPI.Thisfunctiontookastringwithformat"deviceID,serviceID,parameter"andparsedittoaCommandobject.ThisCommandwasthenstoredinaFIFO-buffer,tobeexecutedinthemainloop.
Asystemtohandleevents(suchasdevicestatechanges)wasbuiltbyusingasimilarstrategy.Wheneveraneventoccurred,itwaspassedinthesamestringformatasthecommandstoaninstanceoftheEventBufferclass.Thisbufferconcatenatedalleventswithapipe('|')seperator,anddispatchedtheresultonceeverysecondwithaParticle.publish()call.Allconnectedsubscribers(throughSpencer)werethereforealwaysup-to-datewiththelatestdevicestates.TheconcatenationanddelaywereimplementedbecauseParticle'sAPIlimitedeventpublicationsto1persecond,withsmallburstsallowedof4in1second.
1
Firmware
28
Followingdiagramwillgiveabetteroverviewofthegeneralfunctioningofthefirmware:
CommunicationwiththeRaspberryPiZero
ThePhotonisnotabletocontroltheviewroomdevicesbyitself,itdependsonLIRCandthePythonsoftwarerunningontheRaspberryPi.ItisthereforeimportantthatthePhotoncansendcommandsfrombothhardwareandAPIcallstothePi,andthatthePicansendstateupdatesandcommandresultsback.Serialcommunication(UART)wasusedbecauseoftheeaseofuseandsupportonboththePiandPhotonplatforms.
ThePhotonsentamessagewheneveracommandneededtobeexecutedinthefollowingformat:'dcp',wheredisacharrepresentingthedevice,cisacharacterrepresentingacommand,andpisanoptionalparameter.E.g.whenthe'beamerpoweron'commandisreceivedthroughtheAPI,theBeamerdevice'sexecute()functioniscalledforthe'Power'service,whichsendsthemessage'bp1'(beamerpower1)overtheUART.ThePiwillreceivethismessageandpushittothecommandtree(asdescribedin'Controllingtheviewroom')whichwillmakeLIRCemitthedesiredIRcode.OnesmallexceptionistheOnkyoreceiver,wherethecommandwasprefixedwiththezonenumber.E.g.thecommandforchangingthevolumeforzone1was'o1v35'(Onkyozone1volumeto35)
WheneverthePireceiveda'statechanged'messagefromadevice,itwouldsendamessagetothePhotoninthesameformatasthePhotonsentitscommands.E.gwhensomeoneturnedofftheWeMoswitchitemittedastatechangedeventwhichwaspickedupbythePi.ThePithensenttheserialmessage'wp0'(WeMopower0)tothePhoton.ThePhotonwouldupdateitsinternalWeMostateandpushtheeventintoitsinternaleventbuffer,tobepublishedtoParticle'scloudandupdatingallconnectedclients.
Firmware
29
Hardwarecontrols
Presets
The8presetbuttonswereconnectedthroughavoltagedividertoanADCpin,sotodetectbuttonpresseseachrangeofADCvalueswasmappedtoaspecificbuttonbymanualcalibration.Thepulldownresistorensuredthata0wasmeasuredwhennobuttonwaspressed.
Whenapresetbuttonwaspressed,thenumberofthepressedbuttonwassenttotheRaspberryPi,whereitwasmappedtoapresetandexecuted.Later,thiswassupposedtobereplacedwiththeSpencer-coordinatedpresetsystem,butthiscouldn'tbeimplementedbecausethebackendportionwasn'tfinishedyet.Sointheend,2differentpresetsystemswereinplace:JSON-definedpresetsmappedtohardwarebuttons,andSpencer-definedpresetscalledthroughtheAPI.
TheNeoPixelLED'scorrespondingtothepresetsweremanagedbytheSparkCore-NeoPixellibrary ,whichisaportofAdafruit'sNeoPixellibraryfromArduinotoParticledevices.ThislibrarycontainedanAdafruit_NeoPixelclassthathandledthecomplexcontrolprotocolbehindthescenes.Itsconstructortooksomeconfigurationoptionsasparameters,suchasthetypeandamountofLED's,tomakesureenoughmemorywasreserved.Afterwardsthebegin()functionsetthedatapinasanoutputandturnedallNeoPixelsoff.ThesetPixel(uint16_tn,uint8_tr,uint8_tg,uint8_tb)functionsetthecolordefinedby'r','g'and'b'onapixel'n',andtheshow()functionupdatedtheNeoPixelstomakethischangevisible.
OLEDdisplay
TheSPI-controlledOLEDdisplaywashandledbytheAdafruit_SSD1306library,whichwasportedfromArduinotoParticlebyGithubuser'pkourany' .Thisextensivelibrarycontainedfunctionstoshowtext,graphics,andevenanimationsonthe1"display.IftheRaspberryPiisstillbootingorconnectingtothedifferentdevicesintheviewroom,thedisplayshows'booting'or'connecting'respectively.Otherwisetheviewroomcontrollershows2linesoftextonthedislay:'Zonex'onthetopandeither'Volumeyy'or'Off'onthebottom,wherexisazoneandyyisthevolumeofthatzoneifit'spoweredon.
Thezonethatisdisplayedisconsideredtheactivezone,meaningthatinteractionwiththevolumeknobwillmodifythatzone.Thedisplayisupdatedwheneveravariablethatisdisplayed(volumeandpowerofactivezone)changes,eitherthroughuserinput,anAPIcall,orastatechangeeventfromthedeviceitself.
Pushswitchrotaryencoder
Userinteractionwiththerotaryencodermanipulatedthesignalon2pins,makingitpossibletoalwaysknowwhichdirectiontheknobwasturnedasseeninthisdiagramfromthedatasheet:
2
4
Firmware
30
AsimpleRotaryclasswasmade,whoseconstructorsetthegivenpinsasinputswiththepullupresistorenabled.Aread()functionreadthesignalontheinputpinsandreturned1forclockwiserotation,-1forcounter-clockwiserotation,or0fornorotation.ThisfunctionwasbasedonanexamplebyAdafruitIndustriesintheirtrinketvolumeknobtutorial.
TheOnkyoReceiverDeviceclasskeepstrackofthevolume,power,inputandmutestatusofeachzoneofthereceiver.Whentherotaryisturned,thisvolumestateisincrementedordecrementedfortheactivezone(asdefinedonthedisplay).
Theknobcouldalsobe'clicked'asabutton,whichworkedexactlythesameasanyotherbuttonfromahardwareandcodingpoint-of-view.Ashortclick(lessthanasecond)wouldchangetheactivezonetothenext.Ifthebuttonisheldforlongerthanasecond,thecurrentzone'spoweristoggled.
3
1
Firmware
31
.http://www.wiring.org.co/↩
.https://github.com/technobly/SparkCore-NeoPixel↩
.https://learn.adafruit.com/trinket-usb-volume-knob/code↩
.https://github.com/pkourany/Adafruit_SSD1306↩
1
2
3
4
Firmware
32
Buildingtheendproduct"Wearestuckwithtechnologywhenwhatwereallywantisjuststuffthatworks."–DouglasAdams
PCBOneofthebiggestchallengesinthissecondpartoftheinternshipwasthedesigningofthePCB.Thedesignusedsomedifferentcomponentscomparedtotheprototype:
Allpassivecomponentswerereplacedwithsurfacemountdevices(SMD)variants,mainlywiththeimperial0603footprint(1.6mm×0.8mm).TheParticlePhotondevelopmentboardwasreplacedbyaP1module,whichisbasicallythePhoton'sCPU+Wi-FiradioinasingleSMDchip.Voltageregulation,USBconnectivity,extrabuttonsandanRGBLEDwerenecessarytopower,setupanddebugthisP1module.The8presetpushbuttonswitcheswerereplacedbyaspecialtranslucentrubberbuttonpad,whichneedsaspecificPCBfootprinttowork.Insidethisfootprint,SMDNeoPixels(RGBLED's)weremountedtolightupthebuttonsaccordingtoactivepreset.
ThePCBwasdesignedwithCadSoft'sEagleLightEdition,limitingthePCBtoasizeof10cmx8cmand2layersofrouting.Themaximumallowedsizewaschosentostartthedesignbecausetheusedcomponentswerequitebiganditfeltlikeagoodsizefortheendproduct.Asbestpracticesuggests,thefirststepwasmakingtheelectricaldiagram,andthengivingeachcomponentaplaceontheactualboardstartingwiththebigfootprintsandgoingdowntothetiny0603components.Thistookalotofthought,becausetheendproducthadtobeusableandlookwelltoo.Theconsequencewasthatuser-facingcomponentssuchasbuttonsandthedisplaycouldn'talwaysbeplacedinagoodspotfromanelectricalperspectivebecausetheywouldlookorfeeloutofplaceintheendproduct.
Diagram
Buildingtheendproduct
33
RasberryPiZero
TheRaspberryPiZerodoesn'tcomeinanSMDversion,andbecauseofthelimitedspaceitwouldn'thavebeensoldereddirectlyonthePCBanyway.Therefore,theZerowasattachedonthebottomsideofthePCBonaheader.Thishadtheextrabenefitthatitcouldbeeasilydetachedincaseithadtobereplaced.
ButtonpadwithNeoPixels
ThebuttonpadwasthebiggestcomponentandneededacustomfootprintbecauseaNeoPixelhadtobemountedinsideeachbutton.Thebuttonpaditselfismadefromrubber,withaconductingringinsideeachofthe8keys.WhenakeyispressedtheconductingringtouchesthePCBandissupposedtoconnecttwowirestocompleteacircuit.BothAdafruitandSparkfunhavetheirownfootprintdesignforthesebuttons,buttheydon'tallowanSMDcomponentinsidethebuttonsbecausetheinnerringistoosmallandthefootprintsformaclosedloop:
Lefttoright:Adafruit'sfootprint,Sparkfun'sfootprint,footprintdesignforthisproject.
Thisimagedoesn'tshowthetStopandbStoplayers(thelayersthatdefinewherethesoldermaskhastostop)sothetracesareclear.Inall3casesthereisnosoldermaskonandbetweentherings,sotheconductingringinthebuttonpadcandirectlytouchthecopperlayer.ThecustommadefootprinthasabiggerinnerringsoaNeoPixelcanfitin.BothringsweresplitinhalfandconnectedonthebottomsideofthePCBsothattracescouldreachtheSMDpadsoftheNeoPixel.Thepatternandtracewidthbetweentheringswereadaptedtoprovideoptimalcoverageinthisnewsituation.
Eightofthesefootprintswereplaced,preciselymatchedwiththebuttonpadrings.TheNeoPixelLED'sareconnectedonasingledatanetbecauseoftheirsingle-wiredataprotocol,andtheyarepoweredthroughthe~4.2Vpowertracerunningthroughthemiddle.TheyaregroundedonthegroundplaneonthebottomofthePCB.Eachouterringofthebuttonfootprintsconnectstoadifferentstepofavoltagedivider,whiletheinnerringsareconnectedtoanADCpinontheP1modulewithapulldownresistor.
Buildingtheendproduct
34
ParticleP1
TheP1'slocationonthePCBwascriticalbecauseofbothit'ssizeandmanyconnections(73pads,ofwhich45usedinthisproject).ItwasplacedinthecenterofthePCBandorientedsothattracestothecomponentscouldbeasshortaspossible.
TheP1referencedocumentationrecommends0.1µFand10µFbypasscapacitorsasclosetothepowernetpadsaspossibletoreducevoltagerippleandimprovestability.Eightofthesewereaddedrightnexttotherelevantpinsassuggested(seeimageabove).
SettingupanddebuggingtheP1iseasyoveraUSBconnection,thereforeamicro-USBconnectorwasaddedtothedesign.AgoodUSBconnectionrequireslineterminationresistors ,sotwo20Ohmresistorswereaddedinseriesonthedatalines.
InteractionwiththeP1(e.g.whensomethinggoeswrong)happenswithtwophysicalpushbuttonswitches,aRESETandaMODEbutton.Forthese,theTEConnectivity1825027-2 werechosenandplacedontheedgeofthePCB.Theyareplacedata90degreeanglerelativetothePCBsotheywereaccessiblethroughsmallholesinthesideofthecasing.Thismadesurethatusersdon'taccidentallypressthemandresetorreconfiguretheP1.
ThelastpartforeffectiveP1useisacommon-anodeRGBLED,whichshowstheP1'sstatuswithcolorandblinkingcodes.TheASMB-MTB0-0A3A2 waschosenforitssmallfootprint,brightness,andforwardvoltagesthatdon'texceedtheP1's3.3Vsupply.ThisLEDhadaforwardvoltage2.1Vontheredchannel,and3.1Vontheblueandgreenchannelsaccordingtothedatasheet.Thereforea120Ohmand220Ohmresistorswereusedrespectively,providingtheLEDwith10mAofcurrent((3.3-3.1)/20=0.010,(3.3-2.1)/120=0.010).Thiswaswellbelowthemaximumratingof25mA,andstillcreatedaverybrightLED.
VoltageRegulation
TheP1shouldbepoweredbyastable3.3Vpowersupplycapableofprovidingatleast100mA(plusexternalcomponents)ofcurrent.TheRaspberryPiZero'sUSBpowersupplycouldprovidemorethanenoughcurrentbutrunsat5V.AsmallregulatingcircuitwasbuiltwiththeLM1117 voltageregulator.Toavoidmakingcalculationmistakes,theconfigurationofSparkfun'sPhotonRedboard wascopied.ThisArduino-sizeddevelopmentboardalsopowersaP1modulefroma5VUSBconnection,whichmadeitperfectlysuitabletocopyfortheviewroomcontroller.
1
2
3
45
Buildingtheendproduct
35
Theflipside
AsmanytracesaspossiblewereroutedonthetopsideofthePCB,andthebottomsidewasusedasgroundplane.Agroundplanehassomebenefits:
Easierrouting,becauseeveryconnectiontothegroundcanbemadebyplacingavia.Lesselectricalnoisebecausethebiggroundplanehasaverylowimpedance,meaningthatbigcurrentpulsescanflowtogroundwithoutsignificantvoltagedropsthatdisturbothercomponents.(Thisiscalledgroundbounce )Reducedcrosstalkbetweenadjacenttraces,becausethegroundplaneformsatransmissionlinewiththetracesthusconfiningtheelectromagneticfield.
Checking,ordering,andassembling
WhenthedesignwasfinisheditwascheckedextensivelyboththroughEAGLE'sautomaticDesignRuleCheckerconfiguredforEurocircuits(aPCBmanufacturer)aswellasthehardwareteamatNovemberFive.WhenreviewedandapprovedthenecessaryfileswereuploadedtoEurocircuits,wherethedesignwascheckedagainandtonsofoptions(suchascolorsandmaterials)couldbeconfiguredbeforeplacingthefinalorder.MoreinformationonEurocircuitsandtheirtoolscanbefoundintheEurocircuitsappendix
TheassemblyofthePCBconsistedoftwoparts:solderingtheSMDcomponentsandsolderingthethrough-holecomponents.TheSMDsolderingprocesswasveryinterestingandisdescribedandvisualizedinthesolderingappendix.
Tests&improvements
ThemostthrillingmomentduringthedevelopmentprocesswaspoweringthefinishedPCBforthefirsttime.DiscoveringadesignfaultinthisstagewouldhavebeenfatalfortheprojectbecauseofthemanufacturinganddeliverytimeofanewPCB.Fortunatelyeverythingworkedfineonfirsttry,withtheexceptionthatthebuttonpadreadingswereverynoisyandunstable.Thesebuttonsclearlyweren'tmeantforthevoltage-dividerapproach,andapriorityencoder(e.g.74HC147 )todigitalpinswould'veprobablybeenabettersolution.
Asoftwarefilterwasimplementedinthefirmwaretocounteractthis.Designofthefilterhappenedthroughtrial-and-errorwiththehelpofSciLab andsomedebuggingcodeinthefirmware.WiththehelpoftheSerialToolbox inSciLab,theanalogvaluesmeasuredandprintedbytheP1couldbeplottedandanalyzed.Thebiggestproblemswiththesignalwerebigfluctuationswhenabuttonwasmovingornotpresseddownsecurely,anddifferentvalueswhenabuttonispressedunderaslightangle:
6
7
8
9 10
Buildingtheendproduct
36
Simpleaverageandmeanfiltersweretestedatfirst,buttheydidn'tsucceedinisolatingthewantedsignalsandoftengavefalsepositives(selectingthewrongbutton).Thebestworkingsolutionintheendwasthefollowing:Take1000samples,butdiscardsamplessmallerthan50(unpressedbutton,ornoise).Ifthedifferencebetweenthelowestandhighestvalueinthissetisbiggerthan50,discardtheentireset(unstablereadingsseemtotallyrandomi.e.containnoinformation),otherwisecheckthevaluewiththemappedvaluestofindthecorrectbutton.Thisapproachwasn'textremelyuserfriendlyasthebuttonhadtobeheldanywherebetween0.5-5secondsforagoodreading,butitwasprettygoodateliminatingfalsepositivesandfindingtheactualbutton.
CasingTheblack-and-goldPCBcertainlyhasenoughstyletobeusedasastandaloneproduct,butthat'snotwhattheterm'userexperience'means.Luckily,mypreviousjobasa3DCADdrafterandNovemberFive's'Ultimaker2'3Dprinterprovedafruitfulcombination.
ThesoftwareusedtodesignwastheAutodeskProductDesignSuite,awidelyused,professional&proprietaryCADsuite.IobtainedmultipleAutodeskcertificatesduringapreviousstudyandstudentscangetfreeAutodesklicensesforeducationaluse,sothiswasanobviouschoicetomake.TheinitialprototypewasmadeinAutoCAD3D,theall-aroundCADsketchingprogram.LateronitwasremadeinInventorProfessional,whichisaimedmoreatmechanicaldesignandoffersreallyhelpfulfeaturesspecificallyforplasticsand3Dprintdesign.
Buildingtheendproduct
37
ThefirststepwasrecreatingthePCBandelectricalcomponentsin3Dsotheycouldbeusedasareference.ThePCBitselfwasexportedtoa3DfilefromwithinEagle,whilethecomponentswerealldrawnmanuallyordownloadedfromfreesourcesontheinternetsuchasgrabcad.com.Withthereferenceinplace,thecasingwasdesignedin2parts:abodythatofferedmountingholessotheRaspberryPiZeroandthePCBcouldbemountedsecurelyinplace,andatopthatwouldattachonthebody,andexposedthenecessaryhardwaretotheenduser.Asfastenersforassembly,M2.5screwswerechosenastheywereusedinthePCBandPiZeroandmountingholesareeasiertoprintin3Dthanlatchingmechanismsforexample.Thecompletedesigndrawingscanbefoundinthe'casingdesign'Appendix.
TheUltimaker2canprintindifferentfilamentsthatareavailableinmanydifferentcolors.ThemostusedmaterialforrapidprototypingwasPLA(PolylacticAcid)becauseofthefollowingproperties:
Itiscorn-based,andthusbiodegradable.Usefultominimizedamagetotheenvironmentwhileprintingprototypesortestruns.Itdoesn'treleaseanyhazardouschemicalsduringheating,melting,orhardening.Thetemperaturerangeoverwhichithardensisbiggerthanmostothermaterials,meaningthatfine-grainedtemperaturecontrolislessnecessarytogetgreatresults.
ThebadsideofPLAhowever,isthatitwillloseitsmechanicalpropertiesovertimeandbecomebrittle.It'snotsuitedforpartsthatareusedoftenandshouldlastalongtime.
TheoriginalplanwastoprototypeinPLA,andprintthefinaldesigninathoughermaterialsuchasABS(Acrylonitrile-Butadiene-Styrene).However,the3DprinterstartedtoexperiencecloggingissueswithPLA,whichissupposedtobeeasierthanABS.Therefore,afinalprintwasorderedfromanonline3Dprintingservice.
1
Buildingtheendproduct
38
.http://www.semtech.com/images/datasheet/usb%20line%20termination%20_ag.pdf↩
.http://be.farnell.com/te-connectivity/1825027-2/pushbutton-switch-spst-no-0-05a/dp/2452343↩
.http://be.farnell.com/avago-technologies/asmb-mtb0-0a3a2/led-hb-rgb-0-09w-plcc-4/dp/2401105↩
.http://be.farnell.com/texas-instruments/lm1117mp-3-3/v-reg-ldo-3-3v-1117-sot-223-3/dp/9778195↩
.https://www.sparkfun.com/products/13321↩
.https://en.wikipedia.org/wiki/Ground_plane↩
.https://amplepower.com/primer/ground_bounce/index.html↩
.http://www.learnabout-electronics.org/Downloads/74HC147-10-to-4-line-encoder.pdf↩
.http://www.scilab.org/↩
.https://atoms.scilab.org/toolboxes/serial↩
1
2
3
4
5
6
7
8
9
10
Buildingtheendproduct
39
Conclusion&SummaryIntheend,theresultsatisfiedallrequirementsdescribedunderGoals&Requirements,buthigherqualitycould'vebeenachievedwithmoretimeormoreexperiencefromthestart.It'shardtoprovethecorrectfunctioningoftheentiresysteminwritingorobjectivelymeasurethequalityofsuchasystem,astheonlywaytotrulytestadevicelikethisisbydailyuse.Thefactthattheinitialbreadboardprototypewasalreadybeingusedbycolleagueswhileitwasfarfromfinishedwasagoodindicatorthatthecontrollerwasawelcomeadditiontotheentertainmentroom.
Thesoftwarecontrolledalldevicesintheviewroomperfectly,andmadesurethatup-to-dateconfigurationinformationwasalwaysavailable.PresetscouldbeinstalledusingJSONfilesorthroughtheSpencerbackend,andwereactivatedthroughthe8hardwarebuttons,thecommandlineinterfaceortheSpencermobileapp.TheOSconfigurationcombinedwiththeSupervisordaemonmadesurethesystemsetsupcorrectlyonbootandthesoftwarekeepsrunningnomatterwhat.Perhapswithmoretimethesoftwarecouldhavebeenrefactoredoroptimizedslightly,buttheoverallarchitecturewasclearlyorganizedandperformedwell.
ThehardwareandfirmwareofferedusersfinercontrolovertheOnkyoA/VReceiver,aswellasaccessto8presets.Itworkedgreatwiththesmallexceptionthatthepresetbuttonshadtobehelddownforsometimetoensurecorrectreadings.Thehighpressuretogettoaworkingendproductledtosomeothersuboptimaldecisionsalongtheway,andtimeconstraintsdidn'tallowtomakeasecondversion.E.g.using2microcontrollers(PiandPhoton/P1)gavethebenefitofbothhigh-levelprogrammingandlow-levelhardwarecontrolandspeededdevelopmentupalot,butfeelslikeawasteinanembeddedproduct.Ifasecondversionwouldbemade,usingapriorityencoderanddigitalpinsforthepresetbuttonswoulddefinitelybeabigimprovementtowardsuserexperience.
Buildingtheendproduct
40
Appendices1. ArchLinuxARMsetupandconfiguration2. NeoPixelcurrentdrawmeasurements3. Eurocircuits4. SMDsoldering5. Casingdesign6. UserGuide
Buildingtheendproduct
41
ArchLinuxARMsetupandconfigurationThebootloaderontheRaspberryPistartsitsOSfromamicroSDcard,sothiswasthefirstthingthatneededtobecreated.Choosingapartitioninglayoutislargelydependentonwhatthesystemissupposedtodo,e.g.foraserverthathandlesalotoftrafficitsrecommendedtogivethe/vardirectoryadedicatedpartitionwithaspecializedfilesystem,whilesuchapartitionwouldbeunnecessaryonasystemforpersonaluse. Interestingtonoteisthatwhileonmostsystemsaswappartitionisrecommended,suchapartitionwoulddrasticallyreducethelifespanofanSDcardbecauseoftheirrelativelylowread/writelimits.
Forthisproject,thefollowingpartitioninglayoutwasused:
Name Type Filesystem Size
Boot Primary FAT32 100MiB
Root Primary EXT4 2048MiB
Data Primary EXT4 remaining
Thebootpartitionholdsthekernelimagewhichwillbeloadedonboot,aswellassomebootspecificconfigurationfiles.Asthenameimplies,therootpartitioncontainstherootofthefilesystemandthusallfilesandpackagesthatbelongtotheOSandusers.Insomeusecases,certaindirectoriessuchastheuser's/homeor/tmparemountedondifferentpartitionsbutforthisprojectsimplepartitioningsufficed.Thedatapartitionismeanttocontainprojectspecificdatathatdoesn'tdependonthesystemoritsusers,suchasgitrepositories.Theadvantageofstoringthiskindofdataonaseperatepartitionisthattheentireoperatingsystemcanbereplacedwithoutaffectingtheprojectitself,forexampleincaseofmemorycorruptionorafaultysystemupgrade.Importantsystemconfigurationfileswerealsostoredinaversioncontrolleddirectoryonthedatapartition,andlinkedtotheirexpectedlocationbyusingsymboliclinks(ln-s<src><dest>).Thisway,theentiresystemconfigurationenjoysthebenefitsofversioncontrolsuchasonlinebackup,blamelogs,specificversioncheckouts,andmanymore.
Oncethepartitionswerecreatedandmountedinthelocalfilesystem,ArchLinuxARMwasdownloadedwithGNUwget(wget<downloadserver>)andextractedwithbsdtar(bsdtar-xpf<*.tar.gz>,where-x=extract,-p=preservepermissions,-f=targetisafile).Nexttheextractedfilesweremovedtothedesiredpartitionswithmv(mv<src><dest>),therootdirectorytotherootpartitionandthebootdirectorytothebootpartition.Afterrunningthesynccommand,whichmakessureallfilesareactuallywrittentothemountedpartitions,theSDcardwasfinishedandcouldbeunmounted.
WiththebootableSDcardfinished,itwastimetoboottheRaspberryPiandstartconfiguringthesystem.AsstatedbeforethebaseArchLinuxsystemisverybare,itoffersonlyatextterminalandabasicsetofthemostimportanttools.Bydefault,thereare2users:therootuserroot,andanunprivilegeduseralarm.Toeditconfigurationfiles(whichareownedbytheroot)itwasnecessarytologinasroot.
Toavoidtypingandspellingerrors,thefirststepwastochangethekeyboardlayout,thiswasaccomplishedwiththeloadkeysutility(loadkeysbe-latin1).ThischangeonlyhappensinthecurrentlyloggedinsessionsotomakeitpersistentthelineKEYMAP=be-latin1wasaddedtothefile/etc/vconsole.conf,whichholdstheconfigurationforthevirtualconsole.Forthesakeofinformationsecurity,therootpasswordwaschangedatthistimewiththepasswdprogramandanewunprivilegeduserwascreatedforthedeveloperwiththeuseraddprogram(useradddev-m-s/bin/bash,where-m=givethisusera/homefolder,-s=setthisuser'sdefaultloginshell).
Internetconnectionwasrequiredinordertoinstallorupgradenewpackages,thiswasaccomplishedwiththedefaultwpa-supplicantanddhcpcdprograms,buttheirconfigurationwillnotbediscussedforsecurity'ssake.ArchLinuxisableeding-edgerolling-releaseOS,soit'sagoodideatofrequentlyupdatethepackagelistandupgradethesystem.ThiswasdonewithArchLinux'ownpackagemanager:pacman(pacman-Syu,where-S=synchronize,-y=updatelocalpackagelist,-u=upgradepackages).Inordertoallowthedevelopertoexecuteactionsasanotheruser(mainlytherootuser),sudowasinstalledandthe'dev'userwasaddedtothe/etc/sudoersfilewiththevisudocommand.Thisway,thedevelopercanprependsudotoanycommandtoexecuteitastherootuser.
1
2
ArchLinuxARMsetupandconfiguration
42
Thelastimportantstepatthisstageoftheconfigurationwasmakingsurethedatapartitionwasusable.Asitwasnonecessarypartitionforthesystem,itwouldn'tbemountedbydefault.Byissuingthelsblk-fcommand,thepartition'sUUIDwasfound.Thisvaluewasthenaddedtothe/etc/fstab(filesystemstable)filewiththe'defaults'optionsothattheOSwillautomaticallymountitonboot.
.http://tldp.org/HOWTO/Partition/requirements.html#number↩
.https://en.wikipedia.org/wiki/Flash_memory#Memory_wear↩
1
2
ArchLinuxARMsetupandconfiguration
43
NeoPixelcurrentdrawmeasurementsNote:R,GandBrepresentunsignedbytevaluessetinthefirmware,drivingtheinternalRed,GreenandBlueLEDrespectively.0turnstheLEDoff,while255turnsitonwiththehighestbrightness.
R G B Color Current/LED(mA)
235 51 0 NovemberFiveRed/Orange 22
200 200 200 White 33
100 100 100 White 18
128 0 0 Red 13,5
200 0 0 Red 17,6
0 128 0 Green 11,6
0 200 0 Green 15
0 0 128 Blue 11
0 0 200 Blue 14
128 128 0 Yellow 18
0 128 128 Cyan 15,8
128 0 128 Magenta 18
NeoPixelcurrentmeasurements
44
EurocircuitsEurocircuitsisaBelgianPCBmanufacturerspecializedinprototypesandsmallbatchboards.Itwasfoundedin1991andcurrentlyhasaround200employeesin9countries.Theirmainfocusisonquality,reliabilityandeaseofuse.Withthatinmindtheyprovidegreattoolstooptimizeandcustomizeyourdesignsbeforeprinting,andincludematerialstohelpwiththesolderingprocessinthepackage.
ThePCBConfiguratortool:Dimensions,layers,materials,colors,etc.ofthePCBcanbeconfiguredhere.
ThePCBCheckertool:ChecksthedesignofthePCBandshowswarningsanderrorsincaseanyarefound.
Eurocircuits
45
SolderingEurocircuits'packageincluded3copiesofthePCB,asolderstencilandaholderforthePCBandstencil.Thismadethesolderingprocesseasierthanexpected:
1. Layingoutandlabelingallnecessarycomponents.ThisisimportanttoquicklyandeasilypickandplacethecomponentsonthePCBafterthesolderpasteisapplied.
2. LockingthePCBontheincludedholder,andpreciselyoverlayingandsecuringthesolderstencilontop.
3. Applyingthesolderpaste.Thestencilguaranteesthatthesolderpasteonlygoeswhereit'ssupposedto:ontheSMDpads.
4. PlacingalltheSMDcomponentsontheirsolder-pastedpads.
5. HeatingtheassembledPCB'saccordingthethermalprofileofthesolderpaste(rightoftheheatingplate).
6. Checkingandfixingbadconnectionswithadigitalmicroscopeandfinesolderingiron.
SMDsolderingprocess
46
Someimagesfromthemicroscope.Thebottomrightpictureclearlyshowssolderpastethatdidn'tmelt,anissuethathadtobefixedmanually.
SMDsolderingprocess
47
Casingdesign
CasingDesign
48
CasingDesign
49
UserGuide
50