{"_id":"582b5bf911945a0f006c55ab","user":"56bc6af27c91881900089bac","project":"56a526d4e7a1622b0024fae4","version":{"_id":"576d42354bcd290e00428941","project":"56a526d4e7a1622b0024fae4","__v":1,"createdAt":"2016-06-24T14:22:45.076Z","releaseDate":"2016-06-24T14:22:45.076Z","categories":["576d42354bcd290e00428942","576d42354bcd290e00428943","576d42354bcd290e00428944","576d42354bcd290e00428945","576d42354bcd290e00428946","576d42354bcd290e00428947"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"__v":1,"category":{"_id":"576d42354bcd290e00428942","version":"576d42354bcd290e00428941","project":"56a526d4e7a1622b0024fae4","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-24T19:32:37.467Z","from_sync":false,"order":0,"slug":"documentation","title":"Our Technology"},"updates":["5894be783d33222700db8f47"],"next":{"pages":[],"description":""},"createdAt":"2016-11-15T19:03:21.719Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"Alongside the standard Chirp acoustic protocol, which send data as a series of audible tones, Chirp SDKs are additionally able to support transmitting tones using frequencies that are above the typical human hearing range. This uses the Chirp *ultrasonic* protocol.\n\nThis is a useful approach in scenarios in which noise disturbance must be minimised. This post outlines how to use ultrasonic chirps.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Ultrasonic or near-ultrasonic?\",\n  \"body\": \"The dictionary definition of ultrasound is \\\"audio that is beyond the upper limit of human hearing\\\". A typical adult cannot hear beyond around 15kHz; young people and those with exceptional hearing can often hear above this. Acoustic science technically defines ultrasound as beyond beyond 20kHz.\\n\\nChirp's ultrasonic protocols use frequencies between around 18kHz and 20kHz. This means that we're scientifically near-ultrasonic. In the real world, our \\\"ultrasonic\\\" chirps are not audible to most human ears.\\n\\n[Read more on ultrasonic vs audible frequencies](https://blog.chirp.io/what-we-mean-by-audible-inaudible-and-ultrasonic-36c59560d7fc#.2111deoxc).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Chirp Ultrasonic\"\n}\n[/block]\nIt's quick and easy to get started using Chirp in ultrasonic mode.\n\n1. [Sign up for credentials at the Chirp Admin Centre](http://admin.chirp.io/sign-up), download and set up the SDK for your platform.\n2. [Send us an email](mailto:developers:::at:::chirp.io) requesting access to use ultrasonic mode. We can turn this on without any further action on your part.\n3. In your project, set the Chirp SDK to use the `ultrasonic` protocol. Information on how to do so can be found on the [Chirp Protocols](developers.chirp.io/docs/chirp-protocols) reference, and in the SDK-specific docs.\n4. Create a Chirp object using an ultrasonic identifier (see boxout below).\n\nThat's it. You can now chirp and receive this data as normal.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"As the ultrasonic band has a lower carrying capacity than the audible band, **ultrasonic identifiers are shorter than audible identifiers and use a slightly different syntax**.\\n\\nAudible identifiers are 10 characters long, drawn from the alphabet `[0-9a-v]` (carrying a total of 50 bits of data).\\n\\nUltrasonic identifiers are 8 characters long, drawn from the hex alphabet `[0-9a-f]` (carrying 32 bits of data).\\n\\n**All data carrying capacities and acoustics can be modified for partners in our bespoke protocol programme**\",\n  \"title\": \"Ultrasonic Identifiers\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Streaming Mode\"\n}\n[/block]\nOne of the benefits of ultrasonic chirps is the ability to play a chirp repeatedly without causing a nuisance. This has a number of real-world applications. For example, a proximity beacon could be created by playing an ultrasonic chirp repeatedly from a fixed public location. When a user approaches the beacon with a Chirp-equipped mobile app, the ultrasonic chirp would be detected and can be used to trigger location-specific interactions.\n\nChirp SDKs make it easy to play a chirp on repeat by offering \"streaming mode\". When a chirp is streamed, it plays repeatedly with a small interval between chirps.\n\nThe receiving device should then have streaming mode enabled within the SDK. When enabled, streamingMode instructs the SDK to listen for \"streams\" of chirps rather than one-shot instances, triggering the \"chirp heard\" callback as soon as the stream is detected.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Limitations\"\n}\n[/block]\nAt present, ultrasonic chirps do not support the \"associated data\" feature as offered by the Chirp API. This will be introduced in a future release. Please [contact us](mailto:developers@chirp.io) if you need associated data within your ultrasonic application.","excerpt":"","slug":"ultrasonic","type":"basic","title":"Ultrasonic"}
Alongside the standard Chirp acoustic protocol, which send data as a series of audible tones, Chirp SDKs are additionally able to support transmitting tones using frequencies that are above the typical human hearing range. This uses the Chirp *ultrasonic* protocol. This is a useful approach in scenarios in which noise disturbance must be minimised. This post outlines how to use ultrasonic chirps. [block:callout] { "type": "info", "title": "Ultrasonic or near-ultrasonic?", "body": "The dictionary definition of ultrasound is \"audio that is beyond the upper limit of human hearing\". A typical adult cannot hear beyond around 15kHz; young people and those with exceptional hearing can often hear above this. Acoustic science technically defines ultrasound as beyond beyond 20kHz.\n\nChirp's ultrasonic protocols use frequencies between around 18kHz and 20kHz. This means that we're scientifically near-ultrasonic. In the real world, our \"ultrasonic\" chirps are not audible to most human ears.\n\n[Read more on ultrasonic vs audible frequencies](https://blog.chirp.io/what-we-mean-by-audible-inaudible-and-ultrasonic-36c59560d7fc#.2111deoxc)." } [/block] [block:api-header] { "type": "basic", "title": "Using Chirp Ultrasonic" } [/block] It's quick and easy to get started using Chirp in ultrasonic mode. 1. [Sign up for credentials at the Chirp Admin Centre](http://admin.chirp.io/sign-up), download and set up the SDK for your platform. 2. [Send us an email](mailto:developers@chirp.io) requesting access to use ultrasonic mode. We can turn this on without any further action on your part. 3. In your project, set the Chirp SDK to use the `ultrasonic` protocol. Information on how to do so can be found on the [Chirp Protocols](developers.chirp.io/docs/chirp-protocols) reference, and in the SDK-specific docs. 4. Create a Chirp object using an ultrasonic identifier (see boxout below). That's it. You can now chirp and receive this data as normal. [block:callout] { "type": "warning", "body": "As the ultrasonic band has a lower carrying capacity than the audible band, **ultrasonic identifiers are shorter than audible identifiers and use a slightly different syntax**.\n\nAudible identifiers are 10 characters long, drawn from the alphabet `[0-9a-v]` (carrying a total of 50 bits of data).\n\nUltrasonic identifiers are 8 characters long, drawn from the hex alphabet `[0-9a-f]` (carrying 32 bits of data).\n\n**All data carrying capacities and acoustics can be modified for partners in our bespoke protocol programme**", "title": "Ultrasonic Identifiers" } [/block] [block:api-header] { "type": "basic", "title": "Streaming Mode" } [/block] One of the benefits of ultrasonic chirps is the ability to play a chirp repeatedly without causing a nuisance. This has a number of real-world applications. For example, a proximity beacon could be created by playing an ultrasonic chirp repeatedly from a fixed public location. When a user approaches the beacon with a Chirp-equipped mobile app, the ultrasonic chirp would be detected and can be used to trigger location-specific interactions. Chirp SDKs make it easy to play a chirp on repeat by offering "streaming mode". When a chirp is streamed, it plays repeatedly with a small interval between chirps. The receiving device should then have streaming mode enabled within the SDK. When enabled, streamingMode instructs the SDK to listen for "streams" of chirps rather than one-shot instances, triggering the "chirp heard" callback as soon as the stream is detected. [block:api-header] { "type": "basic", "title": "Limitations" } [/block] At present, ultrasonic chirps do not support the "associated data" feature as offered by the Chirp API. This will be introduced in a future release. Please [contact us](mailto:developers@chirp.io) if you need associated data within your ultrasonic application.