merge translations; add bleio comments; fix minor sphinx issues in midi

7 files changed, 440 insertions, 1 deletions

diff --git a/shared-bindings/bleio/Peripheral.c b/shared-bindings/bleio/Peripheral.c
index 1027bbb1f..cea44486f 100644
--- a/shared-bindings/bleio/Peripheral.c
+++ b/shared-bindings/bleio/Peripheral.c
@@ -192,7 +192,8 @@ const mp_obj_property_t bleio_peripheral_name_obj = {
 //|     services are included in the advertisement packets.
 //|
 //|     :param bool connectable:  If `True` then other devices are allowed to connect to this peripheral.
-//|     :param buf data:  If not None, then send data bytes in advertising packets.
+//|     :param buf data: If `None`, advertise the services passed to this Peripheral when it was created.
+//|       If not `None`, then send the bytes in ``data`` as the advertising packet.
 //|
 STATIC mp_obj_t bleio_peripheral_start_advertising(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     bleio_peripheral_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
diff --git a/shared-bindings/usb_midi/PortIn.c b/shared-bindings/usb_midi/PortIn.c
new file mode 100644
index 000000000..e1e6eabcc
--- /dev/null
+++ b/shared-bindings/usb_midi/PortIn.c
@@ -0,0 +1,128 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <stdint.h>
+
+#include "shared-bindings/usb_midi/PortIn.h"
+#include "shared-bindings/util.h"
+
+#include "py/ioctl.h"
+#include "py/objproperty.h"
+#include "py/runtime.h"
+#include "py/stream.h"
+#include "supervisor/shared/translate.h"
+
+
+//| .. currentmodule:: usb_midi
+//|
+//| :class:`PortIn` -- receives midi commands over USB
+//| ===================================================
+//|
+//| .. class:: PortIn()
+//|
+//|   Not currently dynamically supported.
+//|
+//|   PortIn objects are constructed for every corresponding entry in the USB descriptor and added
+//|   to the ``usb_midi.ports`` tuple.
+//|
+
+STATIC mp_obj_t usb_midi_portin_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    return mp_const_none;
+}
+
+// These are standard stream methods. Code is in py/stream.c.
+//
+//|   .. method:: read(nbytes=None)
+//|
+//|     Read characters.  If ``nbytes`` is specified then read at most that many
+//|     bytes. Otherwise, read everything that arrives until the connection
+//|     times out. Providing the number of bytes expected is highly recommended
+//|     because it will be faster.
+//|
+//|     :return: Data read
+//|     :rtype: bytes or None
+//|
+//|   .. method:: readinto(buf, nbytes=None)
+//|
+//|     Read bytes into the ``buf``.  If ``nbytes`` is specified then read at most
+//|     that many bytes.  Otherwise, read at most ``len(buf)`` bytes.
+//|
+//|     :return: number of bytes read and stored into ``buf``
+//|     :rtype: bytes or None
+//|
+
+// These three methods are used by the shared stream methods.
+STATIC mp_uint_t usb_midi_portin_read(mp_obj_t self_in, void *buf_in, mp_uint_t size, int *errcode) {
+    usb_midi_portin_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    byte *buf = buf_in;
+
+    // make sure we want at least 1 char
+    if (size == 0) {
+        return 0;
+    }
+
+    return common_hal_usb_midi_portin_read(self, buf, size, errcode);
+}
+
+STATIC mp_uint_t usb_midi_portin_ioctl(mp_obj_t self_in, mp_uint_t request, mp_uint_t arg, int *errcode) {
+    usb_midi_portin_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_uint_t ret;
+    if (request == MP_IOCTL_POLL) {
+        mp_uint_t flags = arg;
+        ret = 0;
+        if ((flags & MP_IOCTL_POLL_RD) && common_hal_usb_midi_portin_bytes_available(self) > 0) {
+            ret |= MP_IOCTL_POLL_RD;
+        }
+    } else {
+        *errcode = MP_EINVAL;
+        ret = MP_STREAM_ERROR;
+    }
+    return ret;
+}
+
+STATIC const mp_rom_map_elem_t usb_midi_portin_locals_dict_table[] = {
+    // Standard stream methods.
+    { MP_OBJ_NEW_QSTR(MP_QSTR_read),     MP_ROM_PTR(&mp_stream_read_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_readinto), MP_ROM_PTR(&mp_stream_readinto_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(usb_midi_portin_locals_dict, usb_midi_portin_locals_dict_table);
+
+STATIC const mp_stream_p_t usb_midi_portin_stream_p = {
+    .read = usb_midi_portin_read,
+    .write = NULL,
+    .ioctl = usb_midi_portin_ioctl,
+    .is_text = false,
+};
+
+const mp_obj_type_t usb_midi_portin_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_PortIn,
+    .make_new = usb_midi_portin_make_new,
+    .getiter = mp_identity_getiter,
+    .iternext = mp_stream_unbuffered_iter,
+    .protocol = &usb_midi_portin_stream_p,
+    .locals_dict = (mp_obj_dict_t*)&usb_midi_portin_locals_dict,
+};
diff --git a/shared-bindings/usb_midi/PortIn.h b/shared-bindings/usb_midi/PortIn.h
new file mode 100644
index 000000000..89bb59b71
--- /dev/null
+++ b/shared-bindings/usb_midi/PortIn.h
@@ -0,0 +1,44 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI_PORTIN_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI_PORTIN_H
+
+#include "shared-module/usb_midi/PortIn.h"
+
+extern const mp_obj_type_t usb_midi_portin_type;
+
+// Construct an underlying UART object.
+extern void common_hal_usb_midi_portin_construct(usb_midi_portin_obj_t *self,
+    uint8_t receiver_buffer_size);
+// Read characters.
+extern size_t common_hal_usb_midi_portin_read(usb_midi_portin_obj_t *self,
+    uint8_t *data, size_t len, int *errcode);
+
+extern uint32_t common_hal_usb_midi_portin_bytes_available(usb_midi_portin_obj_t *self);
+extern void common_hal_usb_midi_portin_clear_buffer(usb_midi_portin_obj_t *self);
+
+#endif  // MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI_PORTIN_H
diff --git a/shared-bindings/usb_midi/PortOut.c b/shared-bindings/usb_midi/PortOut.c
new file mode 100644
index 000000000..0588eed90
--- /dev/null
+++ b/shared-bindings/usb_midi/PortOut.c
@@ -0,0 +1,110 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <stdint.h>
+
+#include "shared-bindings/usb_midi/PortOut.h"
+#include "shared-bindings/util.h"
+
+#include "py/ioctl.h"
+#include "py/objproperty.h"
+#include "py/runtime.h"
+#include "py/stream.h"
+#include "supervisor/shared/translate.h"
+
+
+//| .. currentmodule:: usb_midi
+//|
+//| :class:`PortOut` -- sends midi messages to a computer over USB
+//| ==============================================================
+//|
+//| .. class:: PortOut()
+//|
+//|   Not currently dynamically supported.
+//|
+//|   PortOut objects are constructed for every corresponding entry in the USB descriptor and added
+//|   to the ``usb_midi.ports`` tuple.
+//|
+
+STATIC mp_obj_t usb_midi_portout_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) {
+    return mp_const_none;
+}
+
+// These are standard stream methods. Code is in py/stream.c.
+//
+//|   .. method:: write(buf)
+//|
+//|     Write the buffer of bytes to the bus.
+//|
+//|     :return: the number of bytes written
+//|     :rtype: int or None
+//|
+
+STATIC mp_uint_t usb_midi_portout_write(mp_obj_t self_in, const void *buf_in, mp_uint_t size, int *errcode) {
+    usb_midi_portout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    const byte *buf = buf_in;
+
+    return common_hal_usb_midi_portout_write(self, buf, size, errcode);
+}
+
+STATIC mp_uint_t usb_midi_portout_ioctl(mp_obj_t self_in, mp_uint_t request, mp_uint_t arg, int *errcode) {
+    usb_midi_portout_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_uint_t ret;
+    if (request == MP_IOCTL_POLL) {
+        mp_uint_t flags = arg;
+        ret = 0;
+        if ((flags & MP_IOCTL_POLL_WR) && common_hal_usb_midi_portout_ready_to_tx(self)) {
+            ret |= MP_IOCTL_POLL_WR;
+        }
+    } else {
+        *errcode = MP_EINVAL;
+        ret = MP_STREAM_ERROR;
+    }
+    return ret;
+}
+
+STATIC const mp_rom_map_elem_t usb_midi_portout_locals_dict_table[] = {
+    // Standard stream methods.
+    { MP_OBJ_NEW_QSTR(MP_QSTR_write),    MP_ROM_PTR(&mp_stream_write_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(usb_midi_portout_locals_dict, usb_midi_portout_locals_dict_table);
+
+STATIC const mp_stream_p_t usb_midi_portout_stream_p = {
+    .read = NULL,
+    .write = usb_midi_portout_write,
+    .ioctl = usb_midi_portout_ioctl,
+    .is_text = false,
+};
+
+const mp_obj_type_t usb_midi_portout_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_PortOut,
+    .make_new = usb_midi_portout_make_new,
+    .getiter = mp_identity_getiter,
+    .iternext = mp_stream_unbuffered_iter,
+    .protocol = &usb_midi_portout_stream_p,
+    .locals_dict = (mp_obj_dict_t*)&usb_midi_portout_locals_dict,
+};
diff --git a/shared-bindings/usb_midi/PortOut.h b/shared-bindings/usb_midi/PortOut.h
new file mode 100644
index 000000000..dd42d7cdb
--- /dev/null
+++ b/shared-bindings/usb_midi/PortOut.h
@@ -0,0 +1,44 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI_PORTOUT_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI_PORTOUT_H
+
+#include "shared-module/usb_midi/PortOut.h"
+
+extern const mp_obj_type_t usb_midi_portout_type;
+
+// Construct an underlying UART object.
+extern void common_hal_usb_midi_portout_construct(usb_midi_portout_obj_t *self,
+    uint8_t receiver_buffer_size);
+
+// Write characters. len is in characters NOT bytes!
+extern size_t common_hal_usb_midi_portout_write(usb_midi_portout_obj_t *self,
+                              const uint8_t *data, size_t len, int *errcode);
+
+extern bool common_hal_usb_midi_portout_ready_to_tx(usb_midi_portout_obj_t *self);
+
+#endif  // MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI_PORTOUT_H
diff --git a/shared-bindings/usb_midi/__init__.c b/shared-bindings/usb_midi/__init__.c
new file mode 100644
index 000000000..f57d3631b
--- /dev/null
+++ b/shared-bindings/usb_midi/__init__.c
@@ -0,0 +1,78 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <stdint.h>
+
+#include "py/obj.h"
+#include "py/runtime.h"
+
+#include "shared-bindings/usb_midi/__init__.h"
+#include "shared-bindings/usb_midi/PortIn.h"
+#include "shared-bindings/usb_midi/PortOut.h"
+
+#include "py/runtime.h"
+
+//| :mod:`usb_midi` --- MIDI over USB
+//| =================================================
+//|
+//| .. module:: usb_midi
+//|   :synopsis: MIDI over USB
+//|
+//| The `usb_midi` module contains classes to transmit and receive MIDI messages over USB
+//|
+//| Libraries
+//|
+//| .. toctree::
+//|     :maxdepth: 3
+//|
+//|     PortIn
+//|     PortOut
+//|
+//|
+mp_map_elem_t usb_midi_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_usb_midi) },
+    { MP_ROM_QSTR(MP_QSTR_ports), mp_const_empty_tuple },
+    { MP_ROM_QSTR(MP_QSTR_PortIn),   MP_OBJ_FROM_PTR(&usb_midi_portin_type) },
+    { MP_ROM_QSTR(MP_QSTR_PortOut),   MP_OBJ_FROM_PTR(&usb_midi_portout_type) },
+};
+
+// This isn't const so we can set ports dynamically.
+mp_obj_dict_t usb_midi_module_globals = {
+    .base = {&mp_type_dict},
+    .map = {
+        .all_keys_are_qstrs = 1,
+        .is_fixed = 1,
+        .is_ordered = 1,
+        .used = MP_ARRAY_SIZE(usb_midi_module_globals_table),
+        .alloc = MP_ARRAY_SIZE(usb_midi_module_globals_table),
+        .table = usb_midi_module_globals_table,
+    },
+};
+
+const mp_obj_module_t usb_midi_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&usb_midi_module_globals,
+};
diff --git a/shared-bindings/usb_midi/__init__.h b/shared-bindings/usb_midi/__init__.h
new file mode 100644
index 000000000..e81818e04
--- /dev/null
+++ b/shared-bindings/usb_midi/__init__.h
@@ -0,0 +1,34 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Scott Shawcroft
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI___INIT___H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI___INIT___H
+
+#include "py/obj.h"
+
+extern mp_obj_dict_t usb_midi_module_globals;
+
+#endif  // MICROPY_INCLUDED_SHARED_BINDINGS_USB_MIDI___INIT___H