mirror of
https://github.com/espruino/Espruino.git
synced 2025-12-08 19:06:15 +00:00
update docs, and finally use a proper markdown parser!
This commit is contained in:
Gordon Williams
Rhys.Williams
parent
33cfbef6e6
commit
7835cc59f8
@ -442,6 +442,38 @@ void jswrap_nrf_bluetooth_setAdvertising(JsVar *data, JsVar *options) {
|
||||
|
||||
Change the services and characteristics Espruino advertises.
|
||||
|
||||
To expose some information on Characteristic `ABCD` on service `BCDE` you could do:
|
||||
|
||||
```
|
||||
NRF.setServices({
|
||||
0xBCDE : {
|
||||
0xABCD : {
|
||||
value : "Hello",
|
||||
readable : true
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
Or to allow the 3 LEDs to be controlled by writing numbers 0 to 7 to a
|
||||
characteristic, you can do the following. `evt.data` is an array of
|
||||
bytes.
|
||||
|
||||
```
|
||||
NRF.setServices({
|
||||
0xBCDE : {
|
||||
0xABCD : {
|
||||
writable : true,
|
||||
onWrite : function(evt) {
|
||||
digitalWrite([LED3,LED2,LED1], evt.data[0]);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
You can supply many different options:
|
||||
|
||||
```
|
||||
NRF.setServices({
|
||||
0xBCDE : {
|
||||
@ -464,7 +496,7 @@ NRF.setServices({
|
||||
```
|
||||
|
||||
**Note:** UUIDs can be integers between `0` and `0xFFFF`, strings of
|
||||
the form `"0xABCD"`, or strings of the form `""ABCDABCD-ABCD-ABCD-ABCD-ABCDABCDABCD""`
|
||||
the form `"ABCD"`, or strings of the form `"ABCDABCD-ABCD-ABCD-ABCD-ABCDABCDABCD"`
|
||||
|
||||
**Note:** Currently, services/characteristics can't be removed once added.
|
||||
As a result, calling setServices multiple times will cause characteristics
|
||||
@ -564,6 +596,7 @@ Update values for the services and characteristics Espruino advertises.
|
||||
Only services and characteristics previously declared using `setServices` are affected.
|
||||
|
||||
To update the '0xABCD' characteristic in the '0xBCDE' service:
|
||||
|
||||
```
|
||||
NRF.updateServices({
|
||||
0xBCDE : {
|
||||
@ -1053,15 +1086,7 @@ The following filter types are implemented:
|
||||
* `namePrefix` - starting characters of device name
|
||||
|
||||
```
|
||||
NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }] }).then(function(device) {
|
||||
console.log(device);
|
||||
return device.gatt.connect();
|
||||
}).then(function(gatt) {
|
||||
console.log("Connected");
|
||||
gatt.disconnect();
|
||||
}).catch(function() {
|
||||
console.log("Not found");
|
||||
});
|
||||
NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }] }).then(function(device) { ... });
|
||||
// or
|
||||
NRF.requestDevice({ filters: [{ services: ['1823'] }] }).then(function(device) { ... });
|
||||
```
|
||||
@ -1072,6 +1097,40 @@ You can also specify a timeout to wait for devices in milliseconds. The default
|
||||
NRF.requestDevice({ timeout:2000, filters: [ ... ] })
|
||||
```
|
||||
|
||||
As a full example, to send data to another Puck.js to turn an LED on:
|
||||
|
||||
```
|
||||
var gatt;
|
||||
NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }] }).then(function(device) {
|
||||
return device.gatt.connect();
|
||||
}).then(function(g) {
|
||||
gatt = g;
|
||||
return gatt.getPrimaryService("6e400001-b5a3-f393-e0a9-e50e24dcca9e");
|
||||
}).then(function(service) {
|
||||
return service.getCharacteristic("6e400002-b5a3-f393-e0a9-e50e24dcca9e");
|
||||
}).then(function(characteristic) {
|
||||
characteristic.writeValue("LED1.reset()\n");
|
||||
}).then(function() {
|
||||
gatt.disconnect();
|
||||
console.log("Done!");
|
||||
});
|
||||
```
|
||||
|
||||
Or slightly more concisely, using ES6 arrow functions:
|
||||
|
||||
```
|
||||
var gatt;
|
||||
NRF.requestDevice({ filters: [{ namePrefix: 'Puck.js' }]}).then(
|
||||
device => device.gatt.connect()).then(
|
||||
g => (gatt=g).getPrimaryService("6e400001-b5a3-f393-e0a9-e50e24dcca9e")).then(
|
||||
service => service.getCharacteristic("6e400002-b5a3-f393-e0a9-e50e24dcca9e")).then(
|
||||
characteristic => characteristic.writeValue("LED1.reset()\n")).then(
|
||||
() => { gatt.disconnect(); console.log("Done!"); } );
|
||||
```
|
||||
|
||||
Note that you'll have to keep track of the `gatt` variable so that you can
|
||||
disconnect the Bluetooth connection when you're done.
|
||||
|
||||
**Note:** This is only available on some devices
|
||||
*/
|
||||
#if CENTRAL_LINK_COUNT>0
|
||||
@ -1643,69 +1702,3 @@ JsVar *jswrap_nrf_BluetoothRemoteGATTCharacteristic_stopNotifications(JsVar *cha
|
||||
return 0;
|
||||
#endif
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------------
|
||||
* TESTING
|
||||
* ---------------------------------------------------------------------
|
||||
|
||||
// Scanning, getting a service, characteristic, and then writing it
|
||||
|
||||
// getting all services
|
||||
var device;
|
||||
NRF.connect("d1:53:36:1a:7a:17 random").then(function(d) {
|
||||
device = d;
|
||||
console.log("Connected ",d);
|
||||
return d.getPrimaryServices();
|
||||
}).then(function(s) {
|
||||
console.log("Services ",s);
|
||||
return s[2].getCharacteristics();
|
||||
}).then(function(c) {
|
||||
console.log("Characteristics ",c);
|
||||
return c[1].writeValue("LED1.set()\n");
|
||||
}).then(function() {
|
||||
console.log("Written. Disconnecting");
|
||||
device.disconnect();
|
||||
}).catch(function() {
|
||||
console.log("Oops");
|
||||
});
|
||||
|
||||
NRF.connect("d1:53:36:1a:7a:17 random").then(function(d) {
|
||||
device = d;
|
||||
console.log("Connected ",d);
|
||||
return d.getPrimaryService("6e400001-b5a3-f393-e0a9-e50e24dcca9e");
|
||||
}).then(function(s) {
|
||||
console.log("Services ",s);
|
||||
return s.getCharacteristic("6e400002-b5a3-f393-e0a9-e50e24dcca9e");
|
||||
}).then(function(c) {
|
||||
console.log("Characteristics ",c);
|
||||
return c.writeValue("LED1.set()\n");
|
||||
}).then(function() {
|
||||
console.log("Written. Disconnecting");
|
||||
device.disconnect();
|
||||
}).catch(function() {
|
||||
console.log("Oops");
|
||||
});
|
||||
|
||||
|
||||
// ------------------------------ on BLE server (microbit) - allow display of data
|
||||
NRF.setServices({
|
||||
0xBCDE : {
|
||||
0xABCD : {
|
||||
value : "0", // optional
|
||||
maxLen : 1, // optional (otherwise is length of initial value)
|
||||
broadcast : false, // optional, default is false
|
||||
readable : true, // optional, default is false
|
||||
writable : true, // optional, default is false
|
||||
onWrite : function(evt) { // optional
|
||||
show(evt.data);
|
||||
}
|
||||
}
|
||||
// more characteristics allowed
|
||||
}
|
||||
// more services allowed
|
||||
});
|
||||
|
||||
|
||||
|
||||
|
||||
*/
|
||||
|
||||
@ -13,6 +13,9 @@
|
||||
# jswrap_*.c files
|
||||
# ----------------------------------------------------------------------------------------
|
||||
|
||||
# Needs:
|
||||
# pip install markdown
|
||||
|
||||
import subprocess;
|
||||
import re;
|
||||
import json;
|
||||
@ -21,6 +24,7 @@ import os;
|
||||
sys.path.append(".");
|
||||
import common
|
||||
import urllib2
|
||||
import markdown
|
||||
|
||||
# Scans files for comments of the form /*JSON......*/ and then writes out an HTML file describing
|
||||
# all the functions
|
||||
@ -63,33 +67,17 @@ htmlFile = open('functions.html', 'w')
|
||||
def html(s): htmlFile.write(s+"\n");
|
||||
|
||||
def htmlify(d):
|
||||
d = re.sub(r'\n\s*```\n?([^`]+)```', r'\n <pre class="description"><code>\1</code></pre>', d) # code tags
|
||||
d = re.sub(r'```\n?([^`]+)```', r'\n<code>\1</code>', d) # code tags
|
||||
d = re.sub(r'`([^`]+)`', r'<code>\1</code>', d) # code tags
|
||||
d = re.sub(r'\[([^\]]*)\]\(([^\)]*)\)', r'<a href="\2">\1</a>', d) # links tags
|
||||
d = re.sub(r'([^">])(http://[^ ]+)', r'\1<a href="\2">\2</a>', d) # links tags
|
||||
d = re.sub(r'\n###([^\n]*)', r'<B>\1</B>', d) # Heading
|
||||
|
||||
lines = d.split("\n");
|
||||
lines.append("");
|
||||
starStart = False
|
||||
for idx in range(0, len(lines)):
|
||||
line = lines[idx]
|
||||
if re.match('^ *\*',line) and starStart==False:
|
||||
starStart=idx
|
||||
if not re.match('^ *\*',line):
|
||||
if starStart!=False and starStart+2<=idx:
|
||||
l = lines[starStart:idx]
|
||||
for i in range(0,len(l)):
|
||||
l[i] = "<li>"+l[i][l[i].index("*")+1:]+"</li>"
|
||||
lines = lines[0:starStart-1]+["<ul>"]+l+["</ul>"]+lines[idx:]
|
||||
idx += 2+len(l)
|
||||
starStart = False
|
||||
d = "\n".join(lines);
|
||||
|
||||
d = re.sub(r'\*\*([^*]*)\*\*', r'<b>\1</b>', d) # bold
|
||||
d = re.sub(r'\*([^*]+)\*', r'<i>\1</i>', d) # italic
|
||||
return d
|
||||
d = markdown.markdown(d)
|
||||
# replace <code> with newlines with pre
|
||||
idx = d.find("<code>")
|
||||
end = d.find("</code>", idx)
|
||||
while idx>=0 and end>idx:
|
||||
codeBlock = d[idx+6:end]
|
||||
if codeBlock.find("\n")>=0:
|
||||
d = d[0:idx]+"<pre>"+codeBlock+"</pre>"+d[end+7:];
|
||||
idx = d.find("<code>", idx+1)
|
||||
end = d.find("</code>", idx)
|
||||
return d;
|
||||
|
||||
def html_description(d,current):
|
||||
if isinstance(d, list): d = "\n".join(d)
|
||||
@ -98,18 +86,7 @@ def html_description(d,current):
|
||||
d = d.replace(" "+link+" ", " <a href=\"#"+links[link]+"\">"+link+"</a> ")
|
||||
d = d.replace(" "+link+".", " <a href=\"#"+links[link]+"\">"+link+"</a>.")
|
||||
d = d.replace(" "+link+"(", " <a href=\"#"+links[link]+"\">"+link+"</a>(")
|
||||
# Apply <p>, but not inside code snippets
|
||||
inCode = False
|
||||
final = ""
|
||||
for s in htmlify(d).splitlines():
|
||||
if "<code>" in s: inCode = True
|
||||
singleLine = "<code>" in s and "</code>" in s
|
||||
if singleLine or not inCode : final = final + " <p class=\"description\">"
|
||||
final = final + s
|
||||
if singleLine or not inCode : final = final + "</p>"
|
||||
final = final + "\n"
|
||||
if "</code>" in s: inCode = False
|
||||
html(final)
|
||||
html("<div class=\"description\">\n" + htmlify(d) + "\n</div>\n")
|
||||
|
||||
def get_prefixed_name(jsondata):
|
||||
s=""
|
||||
@ -297,7 +274,7 @@ for jsondata in detail:
|
||||
html(" <p class=\"top\"><a href=\"javascript:toppos();\">(top)</a></p>")
|
||||
for j in jsondatas:
|
||||
if (j["type"]=="class" or j["type"]=="library") and j["class"]==className and "description" in j:
|
||||
ds = html_description(j["description"], className)
|
||||
html_description(j["description"], className)
|
||||
|
||||
instances = []
|
||||
for j in jsondatas:
|
||||
@ -327,7 +304,7 @@ for jsondata in detail:
|
||||
insert_mdn_link(jsondata);
|
||||
html(" <p class=\"top\"><a href=\"javascript:toppos();\">(top)</a></p>")
|
||||
html(" <h4>Call type:</h4>")
|
||||
html(" <p class=\"call\"><code>"+get_code(jsondata)+"</code></p>")
|
||||
html(" <div class=\"call\"><code>"+get_code(jsondata)+"</code></div>")
|
||||
if "description" in jsondata:
|
||||
html(" <h4>Description</h4>")
|
||||
desc = jsondata["description"]
|
||||
@ -348,13 +325,13 @@ for jsondata in detail:
|
||||
if isinstance(desc, list): desc = '<br/>'.join(desc)
|
||||
extra = ""
|
||||
if param[1]=="JsVarArray": extra = ", ...";
|
||||
html(" <p class=\"param\"><b> "+param[0]+extra+"</b> "+htmlify(desc)+"</p>")
|
||||
html(" <div class=\"param\">"+htmlify("**"+param[0]+extra+"** "+desc)+"</div>")
|
||||
if "return" in jsondata:
|
||||
html(" <h4>Returns</h4>")
|
||||
desc = ""
|
||||
if len(jsondata["return"])>1: desc=jsondata["return"][1]
|
||||
if desc=="": desc="See description above"
|
||||
html(" <p class=\"return\">"+htmlify(desc)+"</p>")
|
||||
html(" <div class=\"return\">"+htmlify(desc)+"</div>")
|
||||
|
||||
url = "http://www.espruino.com/Reference#"+get_link(jsondata)
|
||||
if url in code_uses:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user