| |
| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| |
| |
| |
| <title>NimBLE Host ATT Client Reference — Apache Mynewt latest documentation</title> |
| |
| |
| |
| |
| <link rel="shortcut icon" href="../../_static/mynewt-logo-only-newt32x32.png"/> |
| |
| |
| |
| |
| <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" /> |
| |
| |
| <link rel="stylesheet" href="../../_static/css/sphinx_theme.css" type="text/css" /> |
| |
| <link rel="stylesheet" href="../../_static/css/bootstrap-3.0.3.min.css" type="text/css" /> |
| |
| <link rel="stylesheet" href="../../_static/css/v2.css" type="text/css" /> |
| |
| <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" /> |
| |
| <link rel="stylesheet" href="../../_static/css/restructuredtext.css" type="text/css" /> |
| |
| |
| |
| |
| <link rel="stylesheet" href="../../_static/css/overrides.css" type="text/css" /> |
| <link rel="index" title="Index" |
| href="../../genindex.html"/> |
| <link rel="search" title="Search" href="../../search.html"/> |
| <link rel="top" title="Apache Mynewt latest documentation" href="../../index.html"/> |
| <link rel="up" title="NimBLE Host" href="ble_hs.html"/> |
| <link rel="next" title="API for btshell app" href="../btshell/btshell_api.html"/> |
| <link rel="prev" title="NimBLE Host Identity Reference" href="ble_hs_id.html"/> |
| |
| |
| <script src="../../_static/js/modernizr.min.js"></script> |
| |
| |
| <script> |
| (function(i, s, o, g, r, a, m) { |
| i["GoogleAnalyticsObject"] = r; |
| (i[r] = |
| i[r] || |
| function() { |
| (i[r].q = i[r].q || []).push(arguments); |
| }), |
| (i[r].l = 1 * new Date()); |
| (a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]); |
| a.async = 1; |
| a.src = g; |
| m.parentNode.insertBefore(a, m); |
| })(window, document, "script", "//www.google-analytics.com/analytics.js", "ga"); |
| |
| ga("create", "UA-72162311-1", "auto"); |
| ga("send", "pageview"); |
| </script> |
| |
| |
| </head> |
| |
| <body class="not-front page-documentation" role="document" > |
| <div id="wrapper"> |
| <div class="container"> |
| <div id="banner" class="row v2-main-banner"> |
| <a class="logo-cell" href="/"> |
| <img class="logo" src="../../_static/img/logo.png"> |
| </a> |
| <div class="tagline-cell"> |
| <h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4> |
| </div> |
| <div class="news-cell"> |
| <div class="well"> |
| <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released September 7, 2023) |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <header> |
| <nav id="navbar" class="navbar navbar-inverse" role="navigation"> |
| <div class="container"> |
| <!-- Collapsed navigation --> |
| <div class="navbar-header"> |
| <!-- Expander button --> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| |
| </div> |
| |
| <!-- Expanded navigation --> |
| <div class="navbar-collapse collapse"> |
| <!-- Main navigation --> |
| <ul class="nav navbar-nav navbar-right"> |
| <li> |
| <a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a> |
| </li> |
| <li class="important"> |
| <a href="/quick-start/">Quick Start</a> |
| </li> |
| <li> |
| <a href="/about/">About</a> |
| </li> |
| <li> |
| <a href="/talks/">Talks</a> |
| </li> |
| <li class="active"> |
| <a href="/documentation/">Documentation</a> |
| </li> |
| <li> |
| <a href="/download/">Download</a> |
| </li> |
| <li> |
| <a href="/community/">Community</a> |
| </li> |
| <li> |
| <a href="/events/">Events</a> |
| </li> |
| </ul> |
| |
| <!-- Search, Navigation and Repo links --> |
| <ul class="nav navbar-nav navbar-right"> |
| |
| </ul> |
| </div> |
| </div> |
| </nav> |
| </header> |
| <!-- STARTS MAIN CONTENT --> |
| <div id="main-content"> |
| |
| |
| |
| |
| |
| |
| <div id="breadcrumb"> |
| <div class="container"> |
| <a href="/documentation/">Docs</a> / |
| |
| <a href="../index.html">BLE User Guide</a> / |
| |
| <a href="ble_hs.html">NimBLE Host</a> / |
| |
| NimBLE Host ATT Client Reference |
| |
| <div class="sourcelink"> |
| <a href="https://github.com/apache/mynewt-nimble/edit/master/docs/ble_hs/ble_att.rst" class="icon icon-github" |
| rel="nofollow"> Edit on GitHub</a> |
| </div> |
| </div> |
| </div> |
| <!-- STARTS CONTAINER --> |
| <div class="container"> |
| <!-- STARTS .content --> |
| <div id="content" class="row"> |
| |
| <!-- STARTS .container-sidebar --> |
| <div class="container-sidebar col-xs-12 col-sm-3"> |
| <div id="docSidebar" class="sticky-container"> |
| <div role="search" class="sphinx-search"> |
| <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search documentation" class="search-documentation" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| <!-- Note: only works when deployed --> |
| <select class="form-control" onchange="if (this.value) window.location.href=this.value"> |
| <option value="/latest" selected> |
| Version: latest |
| </option> |
| <option value="/v1_11_0" > |
| Version: 1.11.0 |
| </option> |
| <option value="/v1_10_0" > |
| Version: 1.10.0 |
| </option> |
| <option value="/v1_9_0" > |
| Version: 1.9.0 |
| </option> |
| <option value="/v1_8_0" > |
| Version: 1.8.0 |
| </option> |
| <option value="/v1_7_0" > |
| Version: 1.7.0 |
| </option> |
| <option value="/v1_6_0" > |
| Version: 1.6.0 |
| </option> |
| <option value="/v1_5_0" > |
| Version: 1.5.0 |
| </option> |
| <option value="/v1_4_0" > |
| Version: 1.4.0 |
| </option> |
| <option value="/v1_3_0/os/introduction" > |
| Version: 1.3.0 |
| </option> |
| <option value="/v1_2_0/os/introduction" > |
| Version: 1.2.0 |
| </option> |
| <option value="/v1_1_0/os/introduction" > |
| Version: 1.1.0 |
| </option> |
| <option value="/v1_0_0/os/introduction" > |
| Version: 1.0.0 |
| </option> |
| <option value="/v0_9_0/os/introduction" > |
| Version: 0.9.0 |
| </option> |
| </select> |
| <div class="region region-sidebar"> |
| <div class="docs-menu"> |
| |
| |
| |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../../index.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../get_started/index.html">Setup & Get Started</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../concepts.html">Concepts</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../tutorials/tutorials.html">Tutorials</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../external_links.html">Third-party Resources</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../os/os_user_guide.html">OS User Guide</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="../index.html">BLE User Guide</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="../ble_sec.html">NimBLE Security</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../ble_setup/ble_setup_intro.html">NimBLE Setup</a></li> |
| <li class="toctree-l2 current"><a class="reference internal" href="ble_hs.html">NimBLE Host</a><ul class="current"> |
| <li class="toctree-l3"><a class="reference internal" href="ble_hs_return_codes.html">Return Codes</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="ble_gap.html">GAP</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="ble_gattc.html">GATT Client</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="ble_gatts.html">GATT Server</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="ble_hs_id.html">Identity</a></li> |
| <li class="toctree-l3 current"><a class="current reference internal" href="#">ATT</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../btshell/btshell_api.html">btshell Usage API</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../mesh/index.html">Bluetooth Mesh</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../../newt/index.html">Newt Tool Guide</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../newtmgr/index.html">Newt Manager Guide</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../mynewt_faq/index.html">Mynewt FAQ</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../../misc/index.html">Appendix</a></li> |
| </ul> |
| |
| |
| |
| </div> |
| </div> |
| </div> |
| <!-- ENDS STICKY CONTAINER --> |
| </div> |
| <!-- ENDS .container-sidebar --> |
| |
| <div class="col-xs-12 col-sm-9"> |
| |
| |
| |
| <div class=""> |
| <div class="rst-content"> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <div class="section" id="nimble-host-att-client-reference"> |
| <h1>NimBLE Host ATT Client Reference<a class="headerlink" href="#nimble-host-att-client-reference" title="Permalink to this headline">¶</a></h1> |
| <div class="section" id="introduction"> |
| <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> |
| <p>The Attribute Protocol (ATT) is a mid-level protocol that all BLE devices use to exchange data. Data is exchanged when |
| an ATT client reads or writes an attribute belonging to an ATT server. Any device that needs to send or receive data |
| must support both the client and server functionality of the ATT protocol. The only devices which do not support ATT |
| are the most basic ones: broadcasters and observers (i.e., beaconing devices and listening devices).</p> |
| <p>Most ATT functionality is not interesting to an application. Rather than use ATT directly, an application uses the |
| higher level GATT profile, which sits directly above ATT in the host. NimBLE exposes the few bits of ATT functionality |
| which are not encompassed by higher level GATT functions. This section documents the ATT functionality that the NimBLE |
| host exposes to the application.</p> |
| </div> |
| <div class="section" id="api"> |
| <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</a></h2> |
| <dl class="c function"> |
| <dt id="c.ble_hs_is_enabled"> |
| <span class="target" id="group__bt__host_1gadd78035cc0e59911bfe8c7622400b158"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">ble_hs_is_enabled</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_is_enabled" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Indicates whether the host is enabled. </p> |
| <p>The host is enabled if it is starting or fully started. It is disabled if it is stopping or stopped.</p> |
| <p><dl class="simple"> |
| <dt><strong>Return</strong></dt><dd><p>1 if the host is enabled; 0 if the host is disabled. </p> |
| </dd> |
| </dl> |
| </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_synced"> |
| <span class="target" id="group__bt__host_1ga766de0eed40adc6e388c4ef5bec03d46"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">ble_hs_synced</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_synced" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Indicates whether the host has synchronized with the controller. </p> |
| <p>Synchronization must occur before any host procedures can be performed.</p> |
| <p><dl class="simple"> |
| <dt><strong>Return</strong></dt><dd><p>1 if the host and controller are in sync; 0 if the host and controller are out of sync. </p> |
| </dd> |
| </dl> |
| </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_start"> |
| <span class="target" id="group__bt__host_1ga5591e554fbc48ebb8dd3f761ad37b450"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">ble_hs_start</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_start" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Synchronizes the host with the controller by sending a sequence of HCI commands. </p> |
| <p>This function must be called before any other host functionality is used, but it must be called after both the host and controller are initialized. Typically, the host-parent-task calls this function at the top of its task routine. This function must only be called in the host parent task. A safe alternative for starting the stack from any task is to call <code class="docutils literal notranslate"><a class="reference internal" href="#group__bt__host_1ga419cec04ac7a359465ddc13e96c06371"><span class="std std-ref"><span class="pre">ble_hs_sched_start()</span></span></a></code>.</p> |
| <p>If the host fails to synchronize with the controller (if the controller is not fully booted, for example), the host will attempt to resynchronize every 100 ms. For this reason, an error return code is not necessarily fatal.</p> |
| <p><dl class="simple"> |
| <dt><strong>Return</strong></dt><dd><p>0 on success; nonzero on error. </p> |
| </dd> |
| </dl> |
| </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_sched_start"> |
| <span class="target" id="group__bt__host_1ga419cec04ac7a359465ddc13e96c06371"></span><span class="pre">void</span> <code class="sig-name descname"><span class="pre">ble_hs_sched_start</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_sched_start" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Enqueues a host start event to the default event queue. </p> |
| <p>The actual host startup is performed in the host parent task, but using the default queue here ensures the event won’t run until the end of main() when this is called during system initialization. This allows the application to configure the host package in the meantime.</p> |
| <p>If auto-start is disabled, the application should use this function to start the BLE stack. This function can be called at any time as long as the host is stopped. When the host successfully starts, the application is notified via the ble_hs_cfg.sync_cb callback. </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_sched_reset"> |
| <span class="target" id="group__bt__host_1ga5c71de1e7267549beba5512a9a73cfd5"></span><span class="pre">void</span> <code class="sig-name descname"><span class="pre">ble_hs_sched_reset</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">reason</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_sched_reset" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Causes the host to reset the NimBLE stack as soon as possible. </p> |
| <p>The application is notified when the reset occurs via the host reset callback.</p> |
| <p><dl class="simple"> |
| <dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">reason</span></code>: The host error code that gets passed to the reset callback. </p></li> |
| </ul> |
| </dd> |
| </dl> |
| </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_evq_set"> |
| <span class="target" id="group__bt__host_1gab993fe7ec28565ab95db29420fed4df5"></span><span class="pre">void</span> <code class="sig-name descname"><span class="pre">ble_hs_evq_set</span></code><span class="sig-paren">(</span><em class="property"><span class="pre">struct</span></em> <span class="pre">ble_npl_eventq</span> <span class="pre">*</span><em><span class="pre">evq</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_evq_set" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Designates the specified event queue for NimBLE host work. </p> |
| <p>By default, the host uses the default event queue and runs in the main task. This function is useful if you want the host to run in a different task.</p> |
| <p><dl class="simple"> |
| <dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">evq</span></code>: The event queue to use for host work. </p></li> |
| </ul> |
| </dd> |
| </dl> |
| </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_init"> |
| <span class="target" id="group__bt__host_1ga69d7274a6c0897109d07a3e60daf04cd"></span><span class="pre">void</span> <code class="sig-name descname"><span class="pre">ble_hs_init</span></code><span class="sig-paren">(</span><span class="pre">void</span><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_init" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Initializes the NimBLE host. </p> |
| <p>This function must be called before the OS is started. The NimBLE stack requires an application task to function. One application task in particular is designated as the “host parent task”. In addition to application-specific work, the host parent task does work for NimBLE by processing events generated by the host. </p> |
| </dd></dl> |
| |
| <dl class="c function"> |
| <dt id="c.ble_hs_shutdown"> |
| <span class="target" id="group__bt__host_1gab97837ef096e47835d9906b1284818ae"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">ble_hs_shutdown</span></code><span class="sig-paren">(</span><span class="pre">int</span> <em><span class="pre">reason</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_hs_shutdown" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Called when the system is shutting down. </p> |
| <p>Stops the BLE host.</p> |
| <p><dl class="simple"> |
| <dt><strong>Return</strong></dt><dd><p>SYSDOWN_IN_PROGRESS. </p> |
| </dd> |
| <dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">reason</span></code>: The reason for the shutdown. One of the HAL_RESET_[…] codes or an implementation-defined value.</p></li> |
| </ul> |
| </dd> |
| </dl> |
| </p> |
| </dd></dl> |
| |
| <dl class="c macro"> |
| <dt id="c.BLE_HS_FOREVER"> |
| <span class="target" id="group__bt__host_1ga8b7d6a49fee6e11e7a8130cbfc8139f7"></span><code class="sig-name descname"><span class="pre">BLE_HS_FOREVER</span></code><a class="headerlink" href="#c.BLE_HS_FOREVER" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Represents an infinite value for timeouts or durations. </p> |
| </dd></dl> |
| |
| <dl class="c macro"> |
| <dt id="c.BLE_HS_CONN_HANDLE_NONE"> |
| <span class="target" id="group__bt__host_1gaa92ebcd7ec84341e7c760a0f0f1e57d4"></span><code class="sig-name descname"><span class="pre">BLE_HS_CONN_HANDLE_NONE</span></code><a class="headerlink" href="#c.BLE_HS_CONN_HANDLE_NONE" title="Permalink to this definition">¶</a><br /></dt> |
| <dd><p>Connection handle not present. </p> |
| </dd></dl> |
| |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| <div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation"> |
| |
| <a href="../btshell/btshell_api.html" class="btn btn-neutral float-right" title="API for btshell app" accesskey="n">Next: API for btshell app <span class="fa fa-arrow-circle-right"></span></a> |
| |
| |
| <a href="ble_hs_id.html" class="btn btn-neutral" title="NimBLE Host Identity Reference" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: NimBLE Host Identity Reference</a> |
| |
| </div> |
| |
| </div> |
| </div> |
| </div> |
| <!-- ENDS CONTENT SECTION --> |
| </div> |
| <!-- ENDS .content --> |
| </div> |
| </div> |
| <footer> |
| <div class="container"> |
| <div class="row"> |
| <div class="col-xs-12"> |
| |
| <p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p> |
| |
| </div> |
| <div class="col-xs-12"> |
| <div class="logos"> |
| <img src="../../_static/img/asf_logo_wide_small.png" alt="Apache" title="Apache"> |
| <small class="footnote"> |
| Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt project logo are either |
| registered trademarks or trademarks of the Apache Software Foundation in the United States and other countries. |
| </small> |
| <a href=""> |
| <img src="../../_static/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| </div> |
| </footer> |
| </div> |
| <!-- ENDS #wrapper --> |
| |
| |
| |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT:'../../', |
| VERSION:'latest', |
| COLLAPSE_INDEX:false, |
| FILE_SUFFIX:'.html', |
| HAS_SOURCE: true, |
| SOURCELINK_SUFFIX: '.txt', |
| LINK_SUFFIX: '.html' |
| }; |
| </script> |
| <script type="text/javascript" src="../../_static/jquery.js"></script> |
| <script type="text/javascript" src="../../_static/underscore.js"></script> |
| <script type="text/javascript" src="../../_static/doctools.js"></script> |
| <script type="text/javascript" src="../../_static/js/bootstrap-3.0.3.min.js"></script> |
| <script type="text/javascript" src="../../_static/js/affix.js"></script> |
| <script type="text/javascript" src="../../_static/js/main.js"></script> |
| |
| |
| |
| </body> |
| </html> |
