<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[All Geek To Me - Medium]]></title>
        <description><![CDATA[All Geek To Me is Chris’ creative outlet for all things techie. - Medium]]></description>
        <link>https://medium.com/all-geek-to-me?source=rss----67613dd1d7bb---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>All Geek To Me - Medium</title>
            <link>https://medium.com/all-geek-to-me?source=rss----67613dd1d7bb---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 22:51:11 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/all-geek-to-me" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Partitioning data on Cosmos DB]]></title>
            <link>https://medium.com/all-geek-to-me/partitioning-data-on-cosmos-db-3016d1a720d3?source=rss----67613dd1d7bb---4</link>
            <guid isPermaLink="false">https://medium.com/p/3016d1a720d3</guid>
            <category><![CDATA[cosmosdb]]></category>
            <category><![CDATA[dotnet]]></category>
            <dc:creator><![CDATA[Chris Wood]]></dc:creator>
            <pubDate>Sat, 11 Mar 2023 13:44:44 GMT</pubDate>
            <atom:updated>2023-03-11T14:04:36.441Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*0561CM68RGXHKWDr" /><figcaption>Photo by <a href="https://unsplash.com/@nananadolgo?utm_source=medium&amp;utm_medium=referral">Nana Smirnova</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>When I first started using Cosmos as the data storage platform for my C# applications, life was pretty straightforward:</p><ul><li>a container could contain 10GB of data without partitioning, or theoretically limitless data with partitioning;</li><li>a non-partitioned container was affordable to a small business like ours, and a partitioned database was eye-wateringly expensive owing to the minimum Request Unit (RU) levels.</li></ul><p><strong>Decision made</strong> — we wouldn’t partition data! We knew we’d never get near 10GB of data given the limited scope of our first few applications, which also wouldn’t be public-facing so wouldn’t receive heavy usage.</p><p>Then things changed.</p><p>The option to have a non-partitioned container went away, and the cost of partitioning became affordable — even compelling! Eventually, the maximum size of data you could store in a logical partition grew to 20GB too.</p><p>For some of our existing really simple applications, we were quite lazy in converting them into partitioned containers. We created a new property on our documents called partitionand set the value on every single record to DefaultPartition. This was quick and easy to do since the likely data size in gigabytes and the levels of usage hadn’t changed; they were always going to be simple, small, low-usage systems.</p><p>But we were also starting to design larger systems by that point that could potentially store tens of gigabytes of data and generate quite a bit more traffic. Thus began our quest to try and figure out how to partition Cosmos data effectively; and, well, it wasn’t straightforward.</p><h3>Quick reminder: how partitioning works</h3><p>There are two types of partition: logical and physical.</p><p>In choosing a partition key, you determine which <em>logical</em><strong> </strong>partition your data sits within. The Cosmos platform then bundles various logical partitions together (or not) on physical storage partitions. You have <em>no</em> control over how Azure does that and don’t even need to care about it, provided you’re partitioning effectively at a logical level.</p><p>So we know we want to partition our data. So how do we choose what we’ll partition <em>by</em>?</p><h3>Problem #1: overly-simplistic examples</h3><p>Of course, the first thing we did was Google the heck out of the question. What we found at the time was lots of examples that did genuinely fulfil the main requirements of a good partition key:</p><ol><li>the value should have a wide range of possible values (high cardinality);</li><li>the value should allow usage (i.e. RU consumption) to be spread as evenly as possible across logical partitions without creating “hot” partitions;</li><li>the partition value shouldn’t change.</li></ol><p>But all the examples were deliberately simplistic (for very understandable reasons).</p><p>Microsoft guidance said, “you could partition by City!”.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ctyP2S0pa60i2lW8.png" /><figcaption>Microsoft example: partitioning by city</figcaption></figure><p>My reaction was “but more people live in big cities, so you’d end up with a London hot partition whereas <a href="https://en.wikipedia.org/wiki/Llanfairpwllgwyngyll">Llanfair­pwllgwyngyll­gogery­chwyrn­drobwll­llan­tysilio­gogo­goch</a> would hardly ever be touched”. So that meets requirement number 1, but not 2 <em>or</em> 3 (since people can move). And, well, we weren’t dealing with towns or cities anyway.</p><p>Even today, the <a href="https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning-overview">Microsoft guidance</a> still uses cities, beef products, vegetables and “Soup, Sauces, and Gravies” as partition value examples.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1015/0*SgDdbWhZ8ODQvKKd.png" /><figcaption>Microsoft: beef products and gravy.</figcaption></figure><h3>Problem #2: forgetting that you’re going to want to use partition key values to actually <em>find</em> records</h3><p>A lot of web-based articles seem to be quite academic about partition key choice. They’ll break down data into partitions by the type of record — a gravy or a beef product, for example — or some other factor that is <em>purely</em> based on the data schema in front of you. Logically, the value that is ultimately chosen as the partition key in these examples makes sense, but only in abstract.</p><p>What they don’t always consider is the <em>purpose</em> of the application and the business context in which it sits, however.</p><p>For example, say you’ve got a document that records flight information. Each instance of an actual flight taken will have its own document.</p><pre>{<br>  &quot;id&quot;: &quot;135b85d9-dc78-4780-a573-91bba00b7fca&quot;,<br>  &quot;flight_code&quot;: &quot;VS045&quot;,<br>  &quot;airline_code&quot;: &quot;VS&quot;,<br>  &quot;scheduled_departure&quot;: &quot;2023-03-11:14:56:00.000Z&quot;,<br>  &quot;actual_departure&quot;: &quot;2023-0311:15:04:42.523Z&quot;,<br>  &quot;departure_airport&quot;: &quot;LHR&quot;,<br>  &quot;arrival_airport&quot;: &quot;JFK&quot;,<br>  &quot;etc&quot;: &quot;etc&quot;<br>}</pre><p>Based purely on the data attributes, you might say “we’ll partition the data by the airline code”. However, there aren’t that many airlines and you run the risk of exceeding 20GB of flight data for an individual airline in due course.</p><p>So maybe we’ll partition by flight code. Based on nothing more than the schema and the above criteria for a good partition key, that choice will tick all the boxes: it supports a wide range of values, you’re spreading the RU load effectively and the value won’t change. Job done, right?</p><p>Now let’s add some business context: the application’s primary use-case is to list all flights from every airline broken down by departure date.</p><p>Suddenly, your partitioning choice is not ideal: you’re always going to have to perform “expensive” cross-partition queries to pull that data for the system’s primary use-case together. These are where you <em>don’t</em> include the partition key in your query allowing a “point query”, leading to a scan of <em>every </em>partition to find data.</p><p>Which brings us back to problem #1: in which business system would you actually, ever, look up customers by city, primarily? Or by gravy? You just wouldn’t.</p><h3>Problem #3: data is often abstract and has no “natural” partition key</h3><p>Closely related to problem #1, most examples use records representing familiar or real-world objects. This makes total sense as they provide an easily-understood, common item that we can apply to our very abstract world of data storage.</p><p>However, not every document will be so lucky as to have easily identifiable partition key or even identifier values. How would you come up with an identifier or partition key for a fostering application or a trade of shares on the market?</p><p>In my experience, the norm has always been that we’re modelling abstract concepts in an abstract world of data storage: life isn’t as neat as the examples we see. We don’t have an immediately usable natural identifier or partition value to use that suits the business context, so we do the next best thing: generate unique identifiers randomly.</p><h3>Problem #4: documents are often related, key propagation requires code overhead, and sometimes all you have is an identifier</h3><p>This was one of my biggest mental blocks. In my head, I didn’t want to partition documents by a commonality that was ultimately irrelevant to how the data would actually be used (e.g. by document type).</p><p>Instead, it made sense (in our business context) to partition by families of documents — for example, the customer, their contracts, their points of contact and their bills should all sit in the same <strong>customer</strong> family and hence the same logical partition. Additionally, a customer has a contract for an electricity <strong>meter point</strong>. The meter point family includes documents about location information, serial numbers and other technical information, readings for each meter, etc.</p><p>The boundaries of the different families of document often intersect like circles on a Venn diagram:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a0l86WL3OkGtpj41qf_eCw@2x.png" /><figcaption>Families of document types and how they intersect</figcaption></figure><p>One partition key option for the customer family of documents could’ve been a customer reference. This would’ve meant storing that value on every type of customer-oriented document. While this is certainly do-able, rippling down the same values between parent and child documents requires overhead in the application code.</p><p>It would also mean knowing the customer reference each time we looked up a value by its identifier. Given our application would be fronted up by a RESTful API with a URL like:</p><p>/api/v1/contracts/{contract-id}</p><p>that customer reference partition key value wasn’t going to be available to look up data in an inexpensive way unless all our APIs used composite IDs to the outside world, such as:</p><p>/api/v1/contracts/{customer-id}:{contract-id}</p><p>Further, how do you handle the situation where two different families of document intersect? You might want to look up the meter points associated with a customer (a customer’s tenancies), <em>and</em> all the customers associated with a meter point (a meter point’s tenants). One partition key <em>can’t</em> serve both families at once.</p><p>OK, enough with the problems! Onto the solutions we came up with for the usage challenges in <em>our</em> business contexts.</p><h3>Solution #1: introducing the PUID</h3><p>You’ve heard of a GUID — a Globally Unique Identifier — also known as a UUID. We came up with an identifier known as a PUID — a Partitioned Unique Identifier. Here’s an example of one:</p><p>a2720172_54d7_43d0_9e9a_fb9fcc4a7c4e</p><p>You’d be forgiven for thinking that’s just a GUID, but if you look very carefully, you’ll see it uses underscores instead of dashes. This is the give-away that we’re looking at a PUID and not a GUID.</p><p>By itself, it’s not much to look at, but look at the identifiers we’ve used for a family of documents:</p><pre><strong>a2720</strong>172_54d7_43d0_9e9a_fb9fcc4a7c4e - customer<br><strong>a2720</strong>087_068f_4e3e_a294_e57e792e95f1 - contract<br><strong>a2720</strong>b6c_1af8_47d0_97d1_e18b2759149f - customer bill 1<br><strong>a2720</strong>2e3_e2dd_4faa_b3ca_133adf8c7542 - customer bill 2<br><strong>a2720</strong>54c_dc18_4008_a37f_103b874ef63a - customer bill 3</pre><p>All the identifiers are different but have the same first five characters. This does mean that generated PUIDs have a higher chance of collision than GUIDs, but we’re not really bothered about generating <em>truly</em> globally unique identifiers. It’s enough for the identifier to be unique within our business application.</p><p>As head of the family, the customer’s identifier is generated first and it’s <em>completely</em> random, just like a GUID would be. Child documents then inherit the first five characters of the their parent’s identifier in their own identifiers.</p><p>The partition key for this particular family is, therefore:</p><p>a2720</p><p>Using this approach means that:</p><ul><li>if we’re trying to find the parent or child document of another document, we know exactly which partition it will be in — the same one as the document we’re already looking at;</li><li>if all we have is an identifier, we know exactly which partition it will be in from the first five characters of the identifier;</li><li>we’ve got high cardinality;</li><li>we can spread RU usage quite evenly across different logical partitions;</li><li>the partition key value doesn’t change;</li><li>any individual partition key can hold up to 20GB of data.</li></ul><h3>Solution #2: dealing with intersecting families</h3><p>Going back to that real scenario we deal with in our own business domain where two different families intersect— customers and meter points — there are a couple of ways we could’ve dealt with this.</p><p>If we’re talking relationally, we’re dealing with a many-to-many relationship representing tenancies. One customer can have multiple meter points, but a meter point can have multiple customers over time (since customers move between properties).</p><p>This is solved by the customer’s contract storing references to the meter points used by the customer, and by the meter point storing referencing all the customers associated with it. In short, a two-way mapping.</p><p>At its simplest, this can be accomplished by the contract document having an array of meter point identifiers and the meter point document having an array of customer identifiers.</p><p>Alternatively, if there’s any danger that the array of values ever gets big enough to make your document size approach Cosmos’ maximum supported size of 2MB, you can create “pointer” documents. A pointer for a customer related to a meter point might be as short and sweet as this:</p><pre>{<br>   &quot;id&quot;: &quot;ef63b54c_dc18_4008_a37f_103b874ef63a&quot;,<br>   &quot;meterPointId&quot;: &quot;ef63b6c_1af8_47d0_97d1_e18b2759149f&quot;,<br>   &quot;customerId&quot;: &quot;a2720172_54d7_43d0_9e9a_fb9fcc4a7c4e&quot;,<br>   &quot;partition&quot;: &quot;ef63b&quot;<br>}</pre><p>Getting a list of customers for a meter point is then a two-step process — get the Customer IDs from all the pointer documents related to the MeterPoint and load the customer documents — but on an RU consumption basis it could be less expensive than repetitive cross-partition scans for business operations that happen very frequently.</p><h3>Solution #3: accept that not everything needs to be a tightly-focused Cosmos query</h3><p>Sometimes you just can’t do something without looking at all partitions, or it’s not worth the investment of time or effort to make it more efficient because it happens so infrequently as part of a background job out-of-ours and without holding up end-users. That’s OK. The world will not end and certainly don’t sacrifice yourself on the altar of purism.</p><p>Also, sometimes the answer isn’t a Cosmos query at all. We index a subset of our documents using <a href="https://azure.microsoft.com/en-us/products/search/">Azure Cognitive Search</a> where we’ve got little ability to predict the criteria or scenarios users will be encountering when exploring our data.</p><h3>One partitioning size doesn’t fit all</h3><p>As I’ve emphasised above, business context and data usage scenarios play a massive role in how you design your partitioned data storage. As such, what’s worked for us may <em>not</em> be a good fit for you.</p><p>Going back to the flight tracking example above, it might be that partitioning by the date of departure would be a much better idea than anything I’ve proposed above regarding PUIDs. It all depends on what you’re doing.</p><p>Similarly, <a href="https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning-overview#use-item-id-as-the-partition-key">Microsoft’s own documentation</a> does remind you that you could just use the document’s id as the partition value for very simple scenarios. For me, this would be scenarios that don’t include logical one-to-many scenarios between documents.</p><p>An alternative to pointer documents is to store duplicate documents against two different partitions too, though that does require the code overhead to do this.</p><p>Nevertheless, I hope all this lived experience will help others in navigating their way through the partitioning maze for the first time, and offers a few techniques that prove useful!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3016d1a720d3" width="1" height="1" alt=""><hr><p><a href="https://medium.com/all-geek-to-me/partitioning-data-on-cosmos-db-3016d1a720d3">Partitioning data on Cosmos DB</a> was originally published in <a href="https://medium.com/all-geek-to-me">All Geek To Me</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing Libraree]]></title>
            <link>https://medium.com/all-geek-to-me/introducing-libraree-6fc88905314f?source=rss----67613dd1d7bb---4</link>
            <guid isPermaLink="false">https://medium.com/p/6fc88905314f</guid>
            <category><![CDATA[azure-functions]]></category>
            <category><![CDATA[wallet]]></category>
            <category><![CDATA[svelte]]></category>
            <category><![CDATA[libraries]]></category>
            <category><![CDATA[librarians]]></category>
            <dc:creator><![CDATA[Chris Wood]]></dc:creator>
            <pubDate>Sun, 02 Jan 2022 23:42:58 GMT</pubDate>
            <atom:updated>2022-01-02T23:42:58.762Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eAeliHg7OelfO9x6ISNdmg.png" /><figcaption>UK library cards in your Apple Wallet or Wallet Passes on Android</figcaption></figure><h3>Libraries are amazing</h3><p>One of the most under-valued assets in British society is our libraries. Quite simply, they’re an utterly amazing portal into other worlds and lives. They’re open to everyone and are completely free.</p><p>Our libraries are also evolving. They’re not the same book-oriented libraries your grandmother would visit; they’re that and more!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/240/0*0e1XRvpxg9pWRzn5.jpg" /><figcaption>All yours for free on Libby!</figcaption></figure><p>Want to get the latest magazines on your iPad for free without paying a penny? Most UK libraries offer you the <a href="https://www.overdrive.com/apps/libby/">Libby</a> app.</p><p>Want to get today’s daily newspapers from the UK and around the world and not have to pay a £20+ subscription? <a href="https://www.pressreader.com/">Pressreader</a> is included with many library services’ memberships.</p><p>Want to read e-books or listen to Audiobooks without paying for each item you download or a £15-per-month Audible subscription? <a href="https://lancashire.borrowbox.com/">Borrowbox</a> gives you just that and is available from most libraries.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*gdiLP1q7FMWrVK4n.jpg" /><figcaption>Borrowbox</figcaption></figure><p>Want a warm space with friendly people and free wifi? Research your family tree using the leading services but without forking out several hundred pounds?</p><p>You get the idea; seriously, join your local library now!</p><h3>Amazing, but also not that great.</h3><p>Library services are <a href="https://www.theguardian.com/books/2020/dec/04/uks-public-libraries-record-another-year-of-cuts-with-yet-more-on-the-way">chronically under-funded</a>. 2020 saw a reduction in funding of £20m and further 14% reduction was anticipated for 2021.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/599/1*TNgTMqBGhcwbBeALU5nPeQ@2x.png" /><figcaption>Searching for library books</figcaption></figure><p>Individual library services don’t really innovate from a technology perspective and procure closed-access systems from a small market of vendors addressing the sector.</p><p>All of this goes some way to explain why some of the actions we take for granted in our modern electronic world still aren’t easily done when it comes to libraries.</p><p>Say you’ve found a book while you’re stood in a bookshop. Surely I can just scan the barcode and find out which of my local libraries has it in stock so I can reserve it? Erm, no, probably not.</p><p>Or say you’re the kind of person who only carries a mobile around; you don’t need a physical wallet because you pay for stuff using Apple or Google Pay. Want to add your library cards to your mobile wallet so you can just drop by whenever the mood takes you? You’re out of luck, buddy.</p><p>Most libraries don’t have an app, those that do don’t have an Apple Wallet capability and that’s most likely because your library uses barcodes that Apple Wallet doesn’t understand. So you still need to carry around those old-fashioned plastic things.</p><p>So, you’re out of luck. Or, at least, you <em>were </em>out of luck.</p><h3>Say ‘hello’ to Libraree!</h3><p>I’ve started a new project to start making awesome library things easier and more relevant to people’s day-to-day technology expectations.</p><p><strong>Libraree catalogue search</strong></p><p>I live on the boundary of several local and unitary authorities so I’m a member of three different library services: Wigan, Lancashire and Manchester. That gives me more opportunity to find a book I want to read, but would otherwise come at the cost of having to search multiple separate library catalogues separately.</p><p>The main <a href="https://www.libraree.org/">Libraree app</a> will allow you to search for books by title, author or ISBN across your choice of library service catalogues and gives you a simple overview of availability:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/500/1*HIqRIHyHaiHB_KDFhGwx-w.png" /></figure><p>One further tap is all it takes to be taken to your library’s catalogue and reservation page.</p><p><strong>Library cards for your Apple Wallet</strong></p><p>Meanwhile the <a href="https://cards.libraree.org/">Libraree Cards</a> site will generate a branded library card for your Apple Wallet or Wallet Passes on Android.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*nC-YM8yzzN93m00uEMFFXQ.png" /></figure><p>It includes a traditional one-dimensional barcode that matches the one on your physical card as well as a QR-code representation which are increasingly supported by self-service kiosks.</p><p>Any details you enter to create your library card are never shared with another party and don’t travel over the internet. In fact, most of the library card generation process happens entirely on your own device.</p><p>Hope you find these new tools useful! I also have a few other library-related ideas that I’ll work on in my free time in 2022.</p><h3>Tech notes</h3><p>Both the catalogue search and Apple Wallet apps were created using <a href="https://svelte.dev/">Svelte</a> for the frontend and <a href="https://azure.microsoft.com/en-gb/services/functions/">Azure Functions</a> written in NodeJS for the backend. Svelte just makes sense to me far more than most other Javascript frameworks, and pairing it with serverless functions that only cost fractions of a penny per execution makes implementation easy and costs cheap.</p><p>Because each library service procures its own catalogue system and because they’re generally closed systems, book searches are carried out using screen scraping via the <a href="https://github.com/LibrariesHacked/catalogues-library">catalogues-library</a> NPM package. This is certainly a point of potential weakness and one I’d love to replace with genuine API connections in the future, but I suspect that would require me to engage with over 300 different library services across the UK, so it’s not a journey I’m eager to embark upon.</p><p>The library card app required the sourcing of logos for all of the UK’s local and unitary authorities as well as coming up with matching branding colours for text and backgrounds. After a ton of initial research, this was largely done using code, using <a href="https://www.selenium.dev/">Selenium</a> to grab Twitter avatars and convert them to PNG images and then using a port of Android’s <a href="https://developer.android.com/training/material/palette-colors">Palette API</a> to derive appropriate colour palettes. The overall dataset was then reviewed by hand and tweaked as necessary.</p><p>Barcodes are scanned and recognised using <a href="https://github.com/ericblade/quagga2">quagga2</a>, to which I’ve contributed a <a href="https://telepen.co.uk/telepen-barcode-information/">Telepen</a> barcode reader. Telepen is one of the most common barcode symbologies used by UK libraries.</p><p>Traditional one-dimensional barcodes are generated using <a href="https://github.com/metafloor/bwip-js">bwip-js</a> and are embedded within the Apple Wallet pass as stripe images. This is how I’ve managed to get some of the older barcode symbologies to appear on the pass.</p><p>I chose to include a QR code because without one of the <em>official</em> Apple barcodes, iPhones <em>won’t</em> increase their brightness to make scanning easier. Additionally, quite a few self-service kiosks will happily scan QR codes now, even if it’s a completely different symbology to the ones used on an authority’s library cards.</p><p>At no point are library card details sent over the internet. That means that the “pkpass” file — actually a renamed zip file with a signature file inside — is generated within the browser, with only the signing happening on a server operated by me. The signature is derived from the checksums of the individual files listed within a manifest file, <em>not</em> based on the zip file itself, which is how a signature can still be generated without the content being transferred anywhere.</p><p>The projects have also introduced me to many of the image manipulation possibilities that are now possible in client-side Javascript (zooming, cropping, resizing, panning) as well handling of Blob objects, allowing you to download a file that’s been created in client memory rather than streamed from a server.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6fc88905314f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/all-geek-to-me/introducing-libraree-6fc88905314f">Introducing Libraree</a> was originally published in <a href="https://medium.com/all-geek-to-me">All Geek To Me</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Developing for the Raspberry Pi Pico in VS Code — Start Coding!]]></title>
            <link>https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-start-coding-bb3834233eff?source=rss----67613dd1d7bb---4</link>
            <guid isPermaLink="false">https://medium.com/p/bb3834233eff</guid>
            <category><![CDATA[vscode]]></category>
            <category><![CDATA[raspberry-pi]]></category>
            <category><![CDATA[pico]]></category>
            <dc:creator><![CDATA[Chris Wood]]></dc:creator>
            <pubDate>Fri, 29 Jan 2021 23:55:18 GMT</pubDate>
            <atom:updated>2021-01-29T23:55:18.620Z</atom:updated>
            <content:encoded><![CDATA[<h3>Developing for the Raspberry Pi Pico in VS Code — Start Coding!</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*L8zcCMteswsJQ0ib.jpeg" /></figure><p>In <a href="https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-getting-started-6dbb3da5ba97"><strong>Part One</strong></a>, we set up your computer so you can make your Raspberry Pi Pico creations in Visual Studio Code. This time, we’ll do the Pico equivalent of <em>Hello World </em>and make the onboard LED flash.</p><h3>Starting a new project</h3><p>Open up VS Code and and go to the <strong>File </strong>menu and then choose <strong>Open</strong>. Navigate to a suitable place and then create a new folder called <strong>LED-Flash</strong>. Once you’ve created that folder, select it and open it up in Code.</p><p>If you can’t already see a <strong>Terminal </strong>panel in Code, switch it on via the <strong>View </strong>menu. All being well and assuming your Pico is plugged into a USB port, you should see that <strong>Pico-Go</strong> has connected to your board!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KToJvVMdHZXKFL3MZNSJRQ.png" /><figcaption>The Pico-Go Console</figcaption></figure><p>If you’ve got a message about not being able to connect to the serial port, you may need to stop any other software that’s using the device (e.g. <a href="https://thonny.org/">Thonny</a>) or physically unplug and then re-plug your Pico into the USB port.</p><p>Click the <strong>+ </strong>button next to the Terminal drop-down to create a second Terminal. Here, you’ll need to type</p><pre>micropy init</pre><p>It will suggest a <strong>project name</strong> — just choose the default:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xU2Emi1za9EXGrrDV0YEqw.png" /></figure><p>Then you’ll need to choose at least these <strong>two option</strong>s:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Iia9IKpPYqQs1tOoIxbtHg.png" /></figure><p>If you intend to put your project in a Git repository afterwards, you’ll probably want the <strong>Git Ignore Template</strong> too.</p><p>Finally, you’ll need to choose the Pico’s <strong>stubs</strong>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JKoT4TouIGpXiP9D_IKoQw.png" /></figure><p>All being well, you should see something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NCLWnNvdQwIp6TcE1j-G2w.png" /></figure><h3>Let’s code!</h3><p>Add a new file to the project called <strong>Flash.py</strong> . At this point, VS Code <em>may </em>ask to restart itself; go ahead, if so.</p><p>Let’s try out the auto-completion and linting! Start typing</p><pre>import mach</pre><p>you should see that it offers “machine” as an auto-complete option:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cJtvdBF6C9QbtIC7BvY6VA.png" /></figure><p>Choose “machine” to complete the first line.</p><p>Then type the following on the next line:</p><pre>import ujson</pre><p>This time, you should see something like this when you hover over the orange wavey line:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pMOuAodygv9jwVZ78asfOA.png" /></figure><p>While <em>ujson </em>is a module in ordinary Python, it’s <em>not</em> available in the version of MicroPython used by the Pico. Linting is telling us that we’ve got a problem we need to fix. Now <strong>delete </strong>the line you just typed.</p><p>From here, type in the following code and you should receive auto-completion help all the way through. Note that parameters on functions aren’t provided; this is a limitation of the stubbing process.</p><pre>import machine<br>import time</pre><pre>pin = machine.Pin(25, machine.Pin.OUT)</pre><pre>while True:<br>    pin.value(1)<br>    time.sleep(1)<br>    pin.value(0)<br>    time.sleep(1)</pre><h3>Run, baby, run!</h3><p>You should now be able to click the <strong>Run </strong>button on the Pico-Go status bar at the bottom of VS Code:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Ga1fTJtA2SFnmcFt2uez0A.png" /></figure><p>The magic should now be happening!</p><h3></h3><p>Anything @JamieLaundon can do.. pic.twitter.com/vBVY99ClYR</p><p>After a few fist-pumps, type <strong>Ctrl + C</strong> to stop your code.</p><h3>Moving code onto the Pico board</h3><p>The code was just <em>running</em> on the board, which is handy for quickly trying something, but we’ve not moved a <em>file</em> containing code to the board yet so it can run automatically when powered up away from a computer.</p><p>Rename <strong>Flash.py </strong>to <strong>main.py</strong> and then click <strong>Upload </strong>on the Pico-Go toolbar. You should see the file is copied to the board and then the board will reboot.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XB8gI72k7vhAJ9-TObhVUw.png" /></figure><p>When it comes back, you should have a flashing light!</p><p>As you can see from the above screenshot, it took my board an extra second to become available to the terminal again, however once you see the “connecting” message, you should be able to use <strong>Ctrl + C</strong> again to stop your code from running.</p><h3>Clearing all files from the board</h3><p>When you’re embarking on your next project, you’ll want to clear any existing code off the board. To do this click the <strong>All Commands </strong>button on the Pico-Go toolbar and then choose</p><pre>Pico-Go &gt; Delete all files from board</pre><p>Answer <strong>Yes </strong>to the confirmation and you’ll see the names of the files that have been deleted, followed by a soft reboot:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sTvtJ8tw8FhQ6HJkcDFFBA.png" /></figure><p>You’re now ready to go and build your next big thing!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bb3834233eff" width="1" height="1" alt=""><hr><p><a href="https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-start-coding-bb3834233eff">Developing for the Raspberry Pi Pico in VS Code — Start Coding!</a> was originally published in <a href="https://medium.com/all-geek-to-me">All Geek To Me</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Developing for the Raspberry Pi Pico in VS Code — Getting Started]]></title>
            <link>https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-getting-started-6dbb3da5ba97?source=rss----67613dd1d7bb---4</link>
            <guid isPermaLink="false">https://medium.com/p/6dbb3da5ba97</guid>
            <category><![CDATA[vscode]]></category>
            <category><![CDATA[pico]]></category>
            <category><![CDATA[raspberry-pi]]></category>
            <dc:creator><![CDATA[Chris Wood]]></dc:creator>
            <pubDate>Fri, 29 Jan 2021 22:44:01 GMT</pubDate>
            <atom:updated>2021-02-06T09:40:22.761Z</atom:updated>
            <content:encoded><![CDATA[<h3>Developing for the Raspberry Pi Pico in VS Code — Getting Started</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QvBEogG2BcplL_mF7VJkXg.png" /></figure><p>I picked up my <a href="https://www.raspberrypi.org/products/raspberry-pi-pico/">Raspberry Pi Pico</a> on the cover of the latest <a href="https://hackspace.raspberrypi.org/articles/where-to-find-hackspace-issue-39">HackSpace</a> magazine last week and have been tinkering with it ever since.</p><p>It’s been a journey in multiple ways: this is my first real attempt at physical computing and it’s meant getting used to Python, which isn’t a language I’ve ever worked with in the past. I’m more of a C# kinda guy who prefers Node when leaving my .NET comfort zone!</p><p>All of the official documentation and tutorials recommend using <a href="https://thonny.org/">Thonny</a> to get started, which I did myself and was delighted to have the onboard LED flashing on or off within a few minutes.</p><p>As good as Thonny is, though, I’d rather use one of my preferred IDEs — <a href="https://code.visualstudio.com/">Visual Studio Code</a> — and missed having any kind of code completion.</p><p>So I investigated and experimented, created two new Github repos [<a href="https://github.com/cpwood/Pico-Stub">1</a>, <a href="https://github.com/cpwood/Pico-Go">2</a>] and a <a href="https://marketplace.visualstudio.com/items?itemName=ChrisWood.pico-go">VS Code extension</a>, and I’m now tinkering merrily with my Pico using Code.</p><p>Here’s how to get started yourself! Part one covers all the one-time setup tasks you’ll need to perform before you begin your first project. It’s aimed at developers with <em>some</em> experience of coding, but <em>doesn’t</em> assume knowledge of Python, MicroPython or microcontrollers specifically.</p><h3>The Very Basics</h3><p>You’ll need a few things installed:</p><ul><li><a href="https://www.python.org/downloads/"><strong>Python</strong></a><strong> </strong>— download and install for your platform;</li><li><a href="https://nodejs.org/en/"><strong>NodeJS</strong></a><strong> </strong>— download and install the LTS version for your platform;</li><li><a href="https://code.visualstudio.com/"><strong>Visual Studo Code</strong></a> — obviously!</li></ul><p>Once you’ve got Python installed, you’ll also want to install <strong>Pip</strong>. Download <a href="https://bootstrap.pypa.io/get-pip.py">this file</a> and then issue the following command from a terminal / Command Prompt window:</p><pre># On Linux or macOS<br>python get-pip.py</pre><pre># On Windows<br>py get-pip.py</pre><p>Keep a lookout for any warnings about Pip not being within your PATH environment variable. If you see such a warning, copy the path it mentions and <a href="https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7">add it into your PATH</a>.</p><p>Also, if you’re on a <strong>Mac</strong>, launch VS Code and from the Command Palette (Command + Shift + P), choose to install the “code” command in PATH:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_X5ZIoWOnJjq1SJ1z1b__w.png" /></figure><h3>Other Prerequisites</h3><p>Right, time to install some stuff specific to our goal: writing code in MicroPython for your Pico board!</p><pre>pip install micropy-cli<br>pip install pylint</pre><p>The <a href="https://github.com/BradenM/micropy-cli"><strong>Micropy CLI</strong></a> is used to quickly setup new projects so that they include code completion and <em>linting </em>(i.e. trying to detect problems and errors).</p><p><a href="https://www.pylint.org/"><strong>Pylint</strong></a> is what will actually do that linting!</p><h3>Configuring Micropy CLI</h3><p>In order to do our code completion and linting, Micropy CLI needs to know a little bit more about the Pico and what it can do. Specifically, it needs to know which Python modules are baked into the board for our use and which functions and properties are included in each.</p><p>This is where the first of my new Github projects comes in: <a href="https://github.com/cpwood/Pico-Stub"><strong>Pico-Stub</strong></a>.</p><p>“Stubs” are what provide Micropy (and Pylint) with that intelligence. They’re generated automatically by running Python code <em>on </em>the Pico board itself. They’re then brought back to a normal computer and are made available for use within Micropy CLI through my repo.</p><p><a href="https://github.com/cpwood/Pico-Stub/archive/main.zip">Download a copy</a> of the repo and extract the zip file. Then add the stubs to Micropy CLI:</p><pre>cd Pico-Stub-main/stubs<br>micropy stubs add micropython-rp2-1_13-290</pre><h3>Other VS Code Extensions</h3><p>Inside VS Code, search for and install the following two extensions:</p><ul><li>ms-python.python</li><li>VisualStudioExptTeam.vscodeintellicode</li></ul><p>Then install my new extension: <a href="https://marketplace.visualstudio.com/items?itemName=ChrisWood.pico-go"><strong>Pico-Go</strong></a>. This allows you to have a REPL-based terminal session within VS Code and provides some handy shortcuts for common tasks.</p><p>And with that, you’re done! Move onto <a href="https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-start-coding-bb3834233eff"><strong>Part Two</strong></a>, where we’ll make an LED flash!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6dbb3da5ba97" width="1" height="1" alt=""><hr><p><a href="https://medium.com/all-geek-to-me/developing-for-the-raspberry-pi-pico-in-vs-code-getting-started-6dbb3da5ba97">Developing for the Raspberry Pi Pico in VS Code — Getting Started</a> was originally published in <a href="https://medium.com/all-geek-to-me">All Geek To Me</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>